Web app redesign

[bgrgicak]

Figma design

@WordPress/playground-maintainers Let's discuss the Web app redesign.
We have a new design that I broke it down into rough tasks and created a timeline.

Timeline

The project is broken up into smaller pieces that can be delivered individually, so we can ship things immediately and avoid feature branches. If a feature requires more PRs like the site manager, we could hide it behind a feature flag (show only in development mode or if a query string exists) until it's ready.

Phase 1: Fundamentals

Let's start by creating the fundamentals like site storage and site switching.
Alongside this, we can start replacing existing modals with new components.

• Site storage
• Site manager sidebar
  • We add a button to the current header
  • The link opens the site manager
  • The button will later be reused in the new header
• Modals and use in the current Web app
  • Import from GitHub
    • Site settings component
  • PR Preview
  • Import zip
  • Export to GitHub
  • Restore from zip

Phase 2: Redesign

Let's expand the fundamentals by adding the site manager editor and support for all existing features in the current view.
After we have feature support, we can update the site header.

• Site manager editor
  • Settings
    • Site details and header without menu
    • Edit settings
    • Header menu
      • Duplicate site
      • Reset site
      • Delete site
    • Theme preview
    • WP admin
    • Edit blueprint
  • Logs
• Site manager preview
• Site view header

Phase 3: Improvements

In the end, let's tackle all non-blocking work and improvements that don't exist in the current design.

• Save temporary site
• Reload temporary site modal
• Offline features
• Share feedback
• E2E tests (ideally as we go)
• Analytics

Features

A detailed list of all the features that the design includes. It will help us break down the project into tasks once we answer all questions.

Expand the full list of features

Site Storage

We need a way to store a list of all sites the user has created. Let's make it flexible so that we can add more data in the future.

• Site list each site in OPFS has a metadata.json file
  • Site title
  • Site slug or site id
  • Blueprint
  • Date created
  • Date last active (used to determine the current site)
  • Logs
• Add site with default settings
• Update site
• Delete site
• Reset site
• Get site

Site manager

The site manager consists of a sidebar, site editor, site preview, and notice sections.

Sidebar

• Search sites
• Site list
  • Select a current site
  • Site favicon
  • Site title
  • Temporary site indicator
• Add site
  • WP PR preview
  • Import from GH
  • Import ZIP
• Offline mode
  • Download all versions button
• Links

Add site

A site can be added using a site settings modal, or by importing from different sources.

• WP PR preview
  • PR URL or Number
  • Extra settings (uses Site settings)
• Import from GH
  • Connect to GitHub
  • Repo select
    • Repo URL
    • Extra settings (uses Site settings)
• Import ZIP
  • Select ZIP

Notice

When offline show a notice at the top.

Site preview

• The preview can be resized by dragging a handle between the preview and the editor.
• On extra large screen only the preview keeps expanding. The editor size is fixed.
• Clicking on the preview will take you to the site.
• The preview is hidden on small screens.

Site editor

Notice

If the current site is temporary, show a notice to save the site.

Header

• Site favicon
• Site title
• Date created
• Links
  • WP admin
    • Opens wp-admin and logs in the user.
  • Open site
• Menu
  • Duplicate
    • Opens an edit settings modal that creates a new site after saving
  • Reset
    • Resets both settings and data
    • Confirm modal
  • Delete
    • Confirm modal
  • Export to GitHub
  • Download as .zip
  • Restore from .zip
  • Share feedback

Export to GitHub

• Connect to GitHub
• Export form
  • PR action type
    • Create new
    • Create draft
    • Update existing
  • PR title (for new and draft)
  • Export (select export type)
    • Theme
      • Select theme
    • Plugin
      • Select plugin
    • wp-content
    • Specific paths
      • Is there a design for this?
    • Repository URL
    • Target repository path
    • Commit message (optional)

Download as .zip

When clicked downloads the site zip.

Restore from .zip

A ZIP upload form. When uploaded the site content is replaced with the ZIP content.

Share feedback

A form for sharing feedback with the Playground team.

• 1-5 score
• How can we improve (optional)
• Email address (optional)

Settings

• Theme
  • Theme screenshot
  • Download theme link
  • Theme name
• Site details
  • Site name
  • Storage type
    • Local
    • Browser
    • temporary
      • Save button
  • WordPress version
  • PHP version
  • Local path
    • For local type only
  • Network access
• WP-admin (This might be removed)
  • Username
  • Password
  • Admin URL
• Edit settings
• Edit blueprint (opens the blueprint editor)

Site settings

• Site name (can be hidden)
• WP version
• PHP version
• Site language
• Storage
• Local path (for local storage only)
  • Path input
  • Directory picker
• Advanced
  • Advanced section can be collapsable or always visible
  • Build version (light/kitchen sink)
  • Networking toggle
• Delete site (when editing an existing site)

Logs

• No logs component
• Log search
• Copy all logs button
• Clear all logs button
• Filters
  • How do filets work?
• Log list
  • Log message
  • Copy message

Site view

• Temporary sites show a confirmation notice if attempting to refresh
• Header
  • Site editor link
  • Title bar

Title bar

• View mode
  • Site name
  • Current page name from the title tag
  • Temporary site indicator
  • Keyboard shortcut indicator
• Edit mode (when clicked)
  • Edit URL input
  • List of predefined pages
  • Edit site button (opens Site settings modal)

[bgrgicak]

What happens when I open Playground with query strings and a blueprint?

[bgrgicak]

Idea 1: A new temporary Playground site is opened.

If there is a site-slug in the URL, I would open the site and ignore the rest.
If there is no site-slug, but there are other query strings or a blueprint, we start a temporary new site.
If there is nothing in the URL, we open the last viewed site.

[adamziel]

@bgrgicak let's frame this in user experience terms, not technical parameter terms. We can make the parameters what we want, but what does the user see?

[bgrgicak]

automatically saving it as persistent when the user makes their first change

Would it be saved with the temporary mode or browser storage?

[adamziel]

Temporary mode means gone when the tab is closed. Every time something is persisted, it has to be with OPFS (or, eventually, with another long-term storage backend).

[bgrgicak]

For v1 we will only show the currently open temporary sites in the site manager. When users save the site it will be converted into a browser-stored site.

In the future, we might explore storing temporary sites as templates, where the site configuration would be visible as a site in the site manager.

[bgrgicak]

What storage type are we going to use for Site storage?

[adamziel]

@bgrgicak MEMFS is an Emscripten concept, that's the filesystem used by Playground in runtime. MEMFS files exist for the duration of the browser tab. Everything we mount, we mount within MEMFS. OPFS is a web browser concept that enables persistent storage between page loads. OPFS files exist potentially indefinitely.

We need a way to store a list of all sites in including temporary sites.

Temporary sites are just the open browser tabs. Persistent "in browser" sites are the OPFS directories. Persistent "local directory" sites are DirectoryHandle objects stored in IndexedDB.

We'll likely have more storage backends in the future and perhaps assuming OPFS directories = active sites won't cut it after all.

In this case, we may need to combine data from inputs, e.g.:

const sitesMeta = [
	(await listTempSitesFromServiceWorker()),
	(await listOPFSsites()),
	(await listIndexedDBSites())
].sort( lastOpened );

Or perhaps we could only combine the list of temporary sites and
sites living in OPFS:

const sitesMeta = [
	(await listTempSitesFromServiceWorker()),
	// OPFS contains both full sites and dummy
	// directories holding just the metadata.json
	// file where the site title, storage type, etc.
	// are stored.
	(await listOPFSsites())
].sort( lastOpened );

[adamziel]

Just to confirm we are on the same page:

• Playground scans a filesystem (OPFS/MEMFS)
• each folder with a metadata.json file is considered a site
• Playground uses the metadata.json files to run sites and store settings

Yup 💯

What if we used only one sites.json file?

That's an option, too. It seems to have a few downsides, though:

• We'll need to synchronize concurrent writes to that file
• The config wouldn't be co-located with the site. If I choose to store my site in a local directory, I won't get the metadata.json file and I won't be able to share my setup with another person, or import the same setup into Playground running in another browser, or import it into an offline tool that doesn't have access to the sites.json file.
• We'll likely need to invent another format for sites stored in git, and then we'll need to implement functions for merging a single site description with a list of sites etc.

Having a single file per site solves all these problems and I can't think of any new problems it generates. What do you think?

This would give us all site info in one place and would make it easier to import/export site info.

In what way would it make it easier to import/export site info?

[bgrgicak]

In what way would it make it easier to import/export site info?

If you move the one file to a new browser, it would have a list of all your sites. But it wouldn't have data, so there are no benefits.
Using one file per site makes sense to me.

[bgrgicak]

Temporary sites are just the open browser tabs.

I think this is where we aren't aligned. From the design, I thought that each new temp site you open would be listed as a site in the sidebar.

Example:

I open playground.wordpress.net#{"features": {"networking": true}}. This starts a new temp site.
The design made me think this site would now show up in the sidebar.
Is that correct?

[adamziel]

There’s just two types of sites in this design:

• Stored permanently
• Living in a browser tab, gone when the tab is closed

There's no concept of a "site that expires after a week". It might be needed eventually, but it's not there in v1.

The temporary sites in the sidebar are just the temporary sites in other open browser tabs.

[bgrgicak]

Where are we going to store the current site info so Playground knows which site to run?

[bgrgicak]

I suggest we reuse site-slug for this.

[adamziel]

+1, assuming the current site info here means how does Playground know which site to run?

[bgrgicak]

current site info here means how does Playground know which site to run?

Yes, I will update the description.

[bgrgicak]

Blueprints commonly use /wordpress/ as the path to the site root folder, but when we have multiple sites in browser storage, they have different root paths. How can we make blueprints reusable and allow users to not care about the root folder path?

[bgrgicak]

• We could automatically prepend it to paths so the user would use / and Playground would convert it to /wordpress/. In this case paths like /tmp/ would also be unique to each site.
• We could keep asking users to use /wordpress/ and rewrite it to the correct path. This would make the /tmp/ path shared between all sites.
• Should the /internal/ folder stay shared?

[adamziel]

Oh, we don't need to do anything at all here. When Playground uses OPFS, it mounts an OPFS path at /wordpress in a similar way as Playground CLI can map /Users/adam/my-sites/my-first-playground-site at /wordpress. In other words, this already "just works".

Should the /internal/ folder stay shared?

The /internal folder lives in VFS and is never stored. It only lives as long as the Playground runtime and holds platform-level plugins needed for the current run (e.g. the SQLite database integration). When the site is closed, even an OPFS site, that entire folder is scraped. Then, on the next website boot, it is created again. This solves all the problems with updating the platform-level plugins – Playground sites will always use their latest versions.

[bgrgicak]

Thanks, I didn't know that!

[bgrgicak]

Site manager shows the site title in a few places how are we going to get it?

[bgrgicak]

• Dynamically when needed. This would require us to query each sites database.
• Whenever a site is selected or site manger is opened, we update the current site and store in the site storage.
  This will get out of sync when someone update the site title in WordPress, but will be synced again when the site manager is opened.
  We could also expand the solution to listen for changes, but it's not needed for the first version.

[adamziel]

Or we could install a platform-level mu-plugin to hook into site title update and write it somewhere, e.g. in <site path>/metadata.json.

[bgrgicak]

Nice! That should make it much easier.

[bgrgicak]

Where will the shared feedback be stored?

[bgrgicak]

• How important is it for us to store the emails? This would introduce PII data, so if we don't need it, let's skip it.
• Could this feedback be comments on a Make post or a GitHub discussion so we don't need to store anything on the Playground server?
• We could send this data to Google Analytics as custom events, but the description and score would be sent separately and couldn't be linked.
• I suggest we don't do this now.

[adamziel]

I suggest we don't do this now.

+1, let's skip this for now.

[bgrgicak]

What would we like to achieve with the new design? How can we measure it using analytics events and page views?

[bgrgicak]

This is a big project for us. Let's ensure we have clear goals and track if we achieved them.

[adamziel]

Qualitatively, I expect to give new users the confidence needed to use Playground without worrying about losing their work. Also, more usage of all the Playground features since the discoverability should go up.

If this happens, we should see a change in overall time spent, new site creation, and PHP/WP version switching. Also, there could be an uptick in PR previews and GitHub imports/exports.

[bgrgicak]

Great points!

In GA we can see how the engagement time changes to see how we affect overall time spent.

new site creation, and PHP/WP version switching

These would be new data points that we don't track today. We could either add events now, so that we have something to compare or just start sending events when the new UI is ready.

I'm ok with not comparing data, for these metrics, seeing the engagement time go up should be a good enough indicator.

[adamziel]

Sounds good! We wouldn't really A/B test anything here – talking to users and keeping track of metrics over time will tell us all we need to know.

[adamziel]

Site manager sidebar
We add only a link at first to the current header

We could also start with a two-pane version – so a sidebar with a sites list and then the site view. Paradoxically, that could require less work. The sidebar and the preview are the same WordPress components as the site editor uses. If we don't adopt the entire layout, we may end up creating a custom sidebar only to drop it later on.

[adamziel]

Just for reference, let's reuse the same React component setup:

Eventually we might turn this Playground UI into its own package or even with the "Sandbox sites" WordPress plugin where you could maintain multiple "site branches".

[bgrgicak]

Site manager sidebar
We add only a link at first to the current header

Sorry, that's outdated.

The idea was to add a temporary button to the current header which opens the site manager. The button would later be reused in the new header.

At the start, the site manager would only include the sidebar and a preview, so we can ship it immediately.
We would add site editing later.

[adamziel]

Thank you so much for fleshing this out @bgrgicak! The storage plumbing, as in OPFS and multi site support, seems to be all in there already. I think the first step here would be the dual pane layout with the list of sites in the sidebar. This should push us to answer a number of remaining UX questions and lay a solid foundation for the rest of it.

[bgrgicak]

The project is now unblocked and we can start working on it.

@brandonpayton I will leave the discussion open for the rest of the week and convert it into an issue after that.
I will use the issue to post project updates.

[brandonpayton]

@brandonpayton I will leave the discussion open for the rest of the week and convert it into an issue after that.
I will use the issue to post project updates.

Thank you, @bgrgicak. I reviewed the design this evening and plan to get to this discussion tomorrow morning.