Editor: expose revisions in the UI for all available post types

[ramonjd]

Related to:

• Phase 2: Customization #33094
• Editor: expose revisions in the UI for all available post types #49601 (comment)

Let's investigate how we can expose revisions in the UI for site components such as:

• templates and template parts Add template revision button #45215
• patterns
• global styles:
  • (Initial experiment) 🚧 Experimental: Global styles revisions #49912. Broken up into the following PRs:
    • Global styles: add revisions UI #50089
    • Style book: make the style book slot generic #49973
      • Find a way to pass fill-specific data to the fill, e.g., title and remove store entry (if possible)
    • Rest API: add /revisions endpoint for global styles #49974

Current issues/bugs

• Links to the editor don't work for template and template parts revisions in the revisions screen #48065
  • Fix Fix revision screen links for templates and template parts wordpress-develop#4229
• Templates and Template part revision history shows wrong first revision #49164
• Global styles: close stylebook if the global styles side bar is not open #50081

[ramonjd]

For global styles revisions, and possibly templates and other site editor post types, I had envisioned something along the lines of the style book, whereby toggling between revisions would take effect in context independent of the editor canvas:

We might be able to genericize the style book slot, and also accommodate a side-by-side view.

I jumped down that particular rabbit hole and found that it involves quite a lot of refactoring and component building, so perhaps too ambitious for an initial revisions offering.

For global styles in particular, it would also be beneficial to isolate the current global styles in the editor canvas, rather than load each revisions's global styles in the editor which is what the MVP #46667 does. That way previewing revisions styles would have no effect on the global styles the user has, potentially changed or loaded, in the editor.

[jasmussen]

That's a good instinct. I wonder if indeed we could show a sort of dots timeline above the scaled down frame, and the items in the sidebar scroll multiple viewports across that timeline.

That's a bit of a dreamy scenario which might run into performance issues, and I would imagine we can also keep in place a single frame like you have here, and load different content inside. This is definitely something to explore in the designs.

[ramonjd]

I wonder if indeed we could show a sort of dots timeline above the scaled down frame, and the items in the sidebar scroll multiple viewports across that timeline

It might be challenging performance-wise, but I like that idea!!

I would imagine we can also keep in place a single frame like you have here, and load different content inside

I've been playing with this scenario in a PR. I think I've nearly cracked it.

2023-04-19.16.00.06.mp4

[jasmussen]

This is pretty fast work, nice! CC: @WordPress/gutenberg-design can we land a version of this soon or does the design need time in the oven?

[paaljoachim]

I do see that important options are inside the 3 dot menu so adding Revisions into it would be a natural progression of this drop down. At a later time we can look at the contents of the 3 dot drop down menu to see if some of the options there should be made more visible. As the 3 dot menu options are fairly hidden away and not openly seen.

What is great with this revision system is that it matches the Story Book method which seems like a method that should be used in the general revision system. Post and Site Editor etc. Clicking a revision one sees the change in the canvas area. What happens if one has made a change to something below or above what one sees in the viewport? Will the screen jump to show adjustments made if one for instance made changes to the bottom of the screen? As smaller changes might not be that easy to see.

I like the wording "Restore and save selected revision" as that says directly what one can do.
I also like seeing the "Save my unsaved changes" as that now will become the latest revision seen.

From what I see in the video I would say this is ready to go.

A later step could be to click some kind of details or down arrow in a revisions button to also see a list of changes that are done. Meaning see the visual change in the canvas and also see a list of changes for a specific revision.

[jameskoster]

Hm, looking at this with fresh eyes I found the video a little confusing.

When you first open the revisions panel there are unsaved changes and there's a warning at the top of the panel saying that if a revisions is restored then those unsaved changes will be lost. Then you change the background, and open the revisions panel again, but this time there's a different UI with the "Save" / "Don't save" buttons. What's the condition that triggers this different UI?

I think the design could use some general polish:

• I assume the Gravatars are the user who saved the changes?
• Revisions list item states (hover, active).
• General spacing / dimensions of the revisions list items – are those based on an existing component?
• Copy can be optimised, and there's a typo: "Restoring a revision will discard this changes".
• In the "Save" / "Don't save" UI both buttons are primary.
  • If we need this UI I still think it'd make more sense in a modal
• "Restore" button might need to be fixed to the bottom of the panel, otherwise it'll disappear out of view when the list is really long?

Happy to help with the visual details!

[ramonjd]

I appreciate the quick feedback @jameskoster @jasmussen and @paaljoachim Very helpful once again 🍺

The demo was hacked together pretty quickly and, yes, needs a major polish, tests (spellcheck!) and probably split up into a couple of PRs to get the groundwork in. It was just to demonstrate the flow.

I believe, at least so far, the benefit of this approach is that we can load both styles and block HTML into the preview pane, so it'd be possible to preview template revisions, and mix them with global styles revisions if we wanted to get jiggy with it.

When you first open the revisions panel there are unsaved changes and there's a warning at the top of the panel saying that if a revisions is restored then those unsaved changes will be lost. Then you change the background, and open the revisions panel again, but this time there's a different UI with the "Save" / "Don't save" buttons

Yeah, the flow is not intuitive. Most of the work was getting the stylebook-like container to work.

Basically I'm checking whether the post is "dirty", that is, if it has unsaved changes in order to give the user a chance to save them before they restore a revision (which will overwrite those unsaved changes).

I think I need to trigger the prompt before we go to save a revision. 🤷 Anyway, I'm hoping your suggestion of the modal to warn about losing unsaved changes will help make the save path clearer to the user.

Still a lot of work to do.

I assume the Gravatars are the user who saved the changes?

Exactly. I'm grabbing the avatar from the author of each global styles revision.

Revisions list item states
General spacing / dimensions of the revisions list items – are those based on an existing component?

After I've cleaned up the impossibly messy code and made it presentable, it'd be great to get a design sweep to help tighten up this.

Copy can be optimised, and there's a typo: "Restoring a revision will discard this changes".

My bl0d is typo. 🤦

If we need this UI I still think it'd make more sense in a modal
"Restore" button might need to be fixed to the bottom of the panel, otherwise it'll disappear out of view when the list is really long?

Good call on both. I'll build it in.

can we land a version of this soon or does the design need time in the oven?

I reckon it'll be easier to test... ultimately... if I split it up into PRs for:

• the new rest endpoint
• genericizing the stylebook
• (maybe) the changes to the __experimentalGetCurrentGlobalStylesId method
• revisions UI and related components

I'll try to power through the first 3 today so we can do the important design review.

[SaxonF]

I think I need to trigger the prompt before we go to save a revision

+1 . Ideally can preview revisions before restoring or needing to decide whether to save/discard current changes.

"Restore and save selected revision" copy is also a little confusing to me. I'm assuming we can't split those two actions? 1. Restore revision to see how it feels 2. Save/publish

[ramonjd]

"Restore and save selected revision" copy is also a little confusing to me. I'm assuming we can't split those two actions? 1. Restore revision to see how it feels 2. Save/publish

I agree. It's over complicating the action. I'm experimenting with confining the save state to the editor, and using the revisions view to only preview revisions and load them into the editor.

This has an added benefit of allowing users to load the revision and carry on editing, without forcing them into a save flow. I'm running on the argument that a user can decide which state to save and when not to.

Screen cast example

[jameskoster]

There's excellent work here, and I'd say the bones are mostly in place. It's probably worth a once-over in terms of design though, just to get all the details right. I'll try and find time asap.

One question – did you consider using the zoomed out view (the same that is invoked when choosing a style variation) rather than the style book 'frame'? That could potentially work better as:

1. It gives a broader view of the current document.
2. Potentially paves the way for a Time Machine-esque stacked revision visualisation in the future.

[paaljoachim]

Zoomed out view.
I was thinking about that in the back of my mind when I gave my feedback above.
A zoomed out view will show the full document even the parts not seen in the zoomed in view. As one gets a broader sense of the changes in all parts of the document. It can also be easier to see the balance of elements in a zoomed out view.

[SaxonF]

@ramonjd That flow works way better imo. Nice one! :)

[ramonjd]

did you consider using the zoomed out view (the same that is invoked when choosing a style variation) rather than the style book 'frame'?

I didn't, but it's something we could try!! I've started pulling apart the experimental PR into smaller PRs to get the foundational work merged.

The final PR, which is not ready yet, will be one with all the UX/UI features, so I'll ping folks when it's ready so we can tweak and retest things.

Once again, thanks for all the help and advice 🙇

[jasmussen]

Really cool to see the collaboration on this one. Kudos, all!

[jameskoster]

Here's a design that updates the flows a little, and explores the general appearance of the revisions timeline:

revisions.mp4

• Seeing as we can't temporarily store unsaved changes, we ask the user if they want to keep or discard them before opening the timeline. Clearly we don't need to do this when there are no unsaved style changes.
• If they elect to save, a new style revision is created.
• Selecting any revision other than the most recent makes the changes dirty.
• Saving styles will 'load' the selected revision, combine it with any changes the user has made since selecting it, and create a new point in the timeline.

There's quite a lot to wrap your head around with this, so I'm almost certainly missing a few things. What do y'all think?

[paaljoachim]

Comparing the video created by Ramon and by James and thinking of other solutions.
Ramon: A button is seen below revisions asking to Save and Restore selected Revision.
James: A modal shows up as one clicks revisions asking to Save Styles.

What about something like this. One clicks to enter Revisions and all the Revisions are greyed out and only the Discard changes or Save button is seen at the top.
User clicks to Discard or Save and both options go away and Styles Revisions are moved up and become clickable.

I am not certain that this is a good approach, but my goal is to keep things in one place. So one does not need to shift focus and eyes to another place on the screen.

---

Seeing the revisions.
I kinda like Ramons and James suggestions seen in both videos.
These are just different ways to present the same information.

Ramons: Avatar icon Revision by -user name- and when the save was done along with the date and time.
James: Time in relation to last save and then an avatar. It looks really nice but there is some missing information such as date and time as well as user name.

[jasmussen]

Nice iterations, Jay, I like the timeline. The following is not meant to block any ongoing work here, but I want to connect some dots to a future interface, revisions as surfaced in the save hub in the editor view:

☝️ The above is an obsolete mockup. But it shows a "Revisions" button in the save hub. Is there an easy way to connect these two disparate elements?

[jameskoster]

If we're going to have per post type revisions, then we need to think a bit about how a global revisions system would interact.

In terms of Styles revisions, I'd expect the behavior in the dark material to be the same. IE click a button to expose a panel containing the revisions list.

[ramonjd]

Thanks for the discussions! In the meantime, I've merged the API/other foundational work for the global styles revisions. The UI/UX PR we can test and discuss is here: #50089

I've tried to build things so that we can leave open the possibility of loading template revisions as well.

[jasmussen]

@ramonjd nice work!

What designs do you need to wrap initial work here?

[mtias]

I think this is done, we can follow up on specific improvements (like surfacing style revisions access in the browse mode of "styles" view).