Prototype: Block-based Blueprints Editor

[adamziel]

Motivation for the change, related issues

Note

You're the most welcome to take over this PR. I won't be able to make progress here in the short term. Do you want a kick-ass Blueprints editing experience? You can make it happen!

A quick prototype of what a block-based Blueprints editor could look like:

Why a UI? We have JSON already...

Why? Because writing JSON is so annoying! You can't easily write 10 lines of PHP code for the runPHP step, you can't reference other files from your local computer, and you need to understand a lot of ideas (like resource types).

A UI editor can provide a tremendously better experience. This prototype doesn't do any of that, but here's what we'll be able to do:

• Create custom steps, like what @akirk started exploring in https://akirk.github.io/playground-step-library/#
• Use data coming directly from local files and directories
• Use a syntax-highlighted code editor for writing PHP code
• Use an embedded Gutenberg instance for editing content in WXR exports
• Autocomplete a list of plugins and themes from the WordPress.org directory
• Confirm all external URLs are reachable
• Eliminate all syntax errors, the UI just won't accept an invalid input
• Export the Blueprint as JSON or ZIP or a git commit
• Edit existing Blueprints
• Embed directly on playground.wordpress.net (or use as a standalone app!)
• ...and so much more!

Why Gutenberg blocks?

My first hunch was to prototype this editor as a standalone app but my intuition was wrong. Everything about building a standalone app sucked.

Here's what Gutenberg gives us for free:

• Forms
• A list view
• Autocompletion
• An entity system
• A design system
• A filterable inserter
• A way to store data
• A drag & drop sorting
• Accessible components
• Offline mode (via Playground PWA)
• Long term support and maintenance
• A distribution system for custom steps (WP plugins)
• Well-defined block API, extensible architecture, nested blocks

And there's more! The experience can be combined with existing WordPress plugins, we'll get new features for free as WordPress grows, we'll improve the WordPress ecosystem, I can keep going.

Testing instructions

Copy this code and paste the contents of steps-quick-n-dirty-prototype.js to your browser's devtools with Gutenberg open. If you want to try it in Playground, go to the "New post" page, open devtools and select "wp (post-new.php)" as the execution context before pasting the code.

Related resources

• https://akirk.github.io/playground-step-library/#
• https://github.com/adamziel/blueprints-ui-builder
• Blueprints JSON editor v2 blueprints-library#53
• Blueprint Builder #773

cc @akirk @dmsnell @bgrgicak @brandonpayton @dawidurbanski @griffbrad @ajitbohra

[ajitbohra]

we had another iteration of the UI builder but there was the urge to use blocks as listed above to benefit from all the foundational pieces we get with the block editor.

demo: https://wp-playground-blueprint-builder.pages.dev/
code: https://github.com/lubusIN/wp-playground-blueprint-builder

The initial discussion on Block-based Visual Builder for Playground was initiated at WCEU 2024 Turin at the Playground Contribution Table. We now have the POC and MVP on its way which will be concluded at WCUS 2024 in Portland.

A sneak peek into what's lined up:

Glimpse of early POC:

blueprint.mp4

[adamziel]

Oh nice @ajitbohra! I'm happy to ditch this PR, it was just a 2 hours exploration to get a better feeling of the problem space, I expected to throw the code away anyway. Would you be interested in starting a PR for this repo? Here's why that would be useful:

• It should make iterating easier as we could move types and the UI in tandem with other Playground packages and the website components.
• A @wp-playground/components package for shared UI elements seems inevitable and we could use this work to bootstrap it. See the related PR.
• There's some code reuse we could do with the new Site Settings form, as in there could be a "Step" that used this exact form:

[ajitbohra]

@adamziel let's keep this PR open for now we can close this once we have the pull with the MVP opened here. yes, we can reuse the efforts, we are on the same page.

@wp-playground/components 💯

[adamziel]

@ajitbohra sounds great, thank you! Aha, there's one change I'd suggest based on the video. The form inputs might be more useful directly in the Edit component within the editor canvas. This would allow the user to understand the entire Blueprint with a visual / screen reader scan and no extra clicks. Also, they'd be able to get the information and edit the information in the same place on the screen. This means less work required to use the editor, and less work required to build it. I know most components use the block inspector, but in this case we're building a form and moving the inputs away from the canvas seems like friction.

[ajitbohra]

@adamziel agree inspector controls are meant for secondary interaction in blocks. video is the initial poc,the mvp we are heading towards uses inline editing for better UX. As seen in screenshot we will have contextual editing so user get Birds Eye view of what blueprint will look like.

[adamziel]

Lovely! By the way, DataForm might be useful here: https://wordpress.github.io/gutenberg/?path=/docs/dataviews-dataform--docs

[ajitbohra]

@adamziel Yes we are already using them for steps with simple forms.

[adamziel]

You are three steps ahead of me @ajitbohra ❤️

[ajitbohra]

@adamziel This is what we have so far after polishing things at #WCUS

playground-blueprint-builder-social.mp4

for a quick test drive
Playground Demo

We have the code here for now https://github.com/lubusIN/block-editor-for-playground-blueprint/tree/dev

Some cleanup and we are good to transition this here.

[adamziel]

@ajitbohra slick! 😍 Such a lovely, lovely work, I thank you with all my heart for getting it so far! It will be so, SO helpful and also it will also unlock extending Blueprints with new steps!

[asirota]

@ajitbohra that does look super! A few ideas

For the plugin block when using slug, is it possible to query the repo to search for a plugin slug rather than having to know it ahead of time. This would be a great help

Alternatively there also could be a way to choose from a list of plugins the current site already has. This is especially useful if you're building a blueprint to recreate the current site.

And a very long term goal it would super sweet to recreate a plugin based on the current site options, server settings and plugin and theme profile with one click. Sort of a plugin generator, but that's probably down the road!

[ajitbohra]

@asirota

The current builder is MVP and we have plans to expand this. Better UI/UX for plugin, theme, and options selection is already on my wishlist. Big yes for generating a blueprint from the site and seems like you read my mind :)

We will get this MVP rolling and put down a rough roadmap on what more we can done.

[asirota]

That's great to hear
@ajitbohra I put an issue with some of the core features to reverse engineer a blue print together too in #1809.

[jarekmorawski]

As part of the ongoing Playground UX overhaul, I put together some designs that I hope may help bring the Blueprint Editor to wp-admin's new design language. They build off of @ajitbohra's fantastic work on the block builder (kudos!) and mostly refine some stylistic choices and microinteractions.

Let me know what you think. Happy to do another take if you feel it needs further work. This is a very high-level exploration and many details are missing, but I hope it'll spark an interesting discussion about the future UX of blueprint editing.

The workflow-like layout is probably the most significant update. Though technically still blocks, I made the actions look like boxes to avoid confusing users who mostly associate blocks with content displayed on the front-end.

Each box displays the most important information about the associated action:

• Action type label, e.g. Write or Activate
• Action type icon
• Primary information, e.g. last segment of the file path, username, code language, etc
• Secondary information, e.g., code or plugin name/link

Users can move actions up and down when they select them in the canvas.

I also renamed all steps to "Actions" (it can be a good umbrella term given that each item impacts the site's config or data in some way) and rearranged and converged the items in the Inserter to make the list shorter and more concise (e.g. Install, then choose Plugin or Theme in the next step vs. Install Plugin and Install Theme).

Note that it's just my own thinking and if it isn't reasonable or feasible, feel free to adjust.

In the sidebar, users can edit each action's settings and data (doing so in the canvas doesn't feel well-aligned with where the site editor is heading and some of the latest changes to block editing UX) and access the blueprint's global settings, like WP version, status, categories, etc.

cc @adamziel @bgrgicak

[adamziel]

Lovely explorations @jarekmorawski! One thing that jumps out for me is the writeFile step – ideally it wouldn't be a single line of text, but we'd have a proper code editor there with syntax highlighting and all. That's a nitpick, though. I love the workflow-like visual connections between the steps.

Another thing that stands out is that these steps are not immediately editable and that the interactions are hidden in the block inspector. It would be useful to make them immediately interactive – see the conversation above about this exact topic.

[asirota]

Amazing look! Could there be a step to lever runPHP to create a page or post? Like a shortcut to automatically create the necessary code to read a page/post, it's contents/metadata and then generate the PHP to recreate it in a step. That would be such a killer demo.

[adamziel]

@asirota the importWxr step block could display an embedded Playground where you'd be able to edit posts, pages, etc :)

[asirota]

True dat! @adamziel

[ajitbohra]

PR to add the builder #2008

@jarekmorawski thanks for the explorations 🌟 I have incorporated a few of them in the above pull.

[dawidurbanski]

@ajitbohra This looks fantastic! @adamziel I'm just wondering wouldn't this be more suitable for PR in the playground-tools repo?