Editor Welcome Tour Component

[autumnfjeld]

This PR continues from initial spike.
Project issue details user facing requirements and project links.

Changes proposed in this Pull Request

• Add new Welcome Tour Component
• Remove NUX modal

Details:

• create portal for the Tour component such that user can interact with either Tour or the Editor
• Tour card can be minimized and then re-maximized
• pagination for Tour cards
• foundations that allow for conditional content (e.g. welcome content customized for different onboarding experiences)
• user can interact in both Tour & editor
• Set up correct icons / discuss with design as icons should come from GB icons package .
• images should be preloaded to avoid janky renders
• wire up wp.data things to save state: isNuxEnabled to know when to show the Tour
• verify that we can repurpose is_nux_enabled or if we need to create another flag a different flag for tracking when editor is opened for the first time
• remove old NUX modal code UNLESS we are doing an A/B test
• Move Tour to own folder to allow for A/B testing of NUX vs Tour
• translations: TODO in followup PR
• tracking: TODO in followup PR

Issues:

• tour not loading in safari
• Not clear if the <LaunchWpcomNuxTour /> component is unmounting. I did not observe the useEffect cleanup happening.

Testing instructions

There are three places used to determine whether to show the NUX dialog, in the following order:

1. Local storage in the browser
2. The user attribute wpcom-block-editor-preferences['nux-status']
3. The user metadata field wpcom_block_editor_nux_status

1) reset local storage

You must clear local storage for the site you are working with (from the Application tab of the chrome dev tools)

2) Reset the user attribute wpcom-block-editor-preferences['nux-status']

The user attribute 'wpcom-block-editor-preferences' => 'nux-status' is used to determine whether to show the welcome tour.
This flag is also cached in local storage in the browser
It can be reset like so from a sandbox: (for your user_id)

wpsh
> update_user_attribute( 180278607, 'wpcom-block-editor-preferences', [ 'nux-status' => 'enabled' ] );

At this point reloading the page should show the tour again

3) Reset the user metadata field wpcom_block_editor_nux_status

This field is only used if the user attribute hasn't been set yet

wp user meta update <USER_NAME> wpcom_block_editor_nux_status enabled

Fixes #47691

[matticbot]

Test live: https://calypso.live/?branch=add/editor-welcome-tour

[matticbot]

This PR does not affect the size of JS and CSS bundles shipped to the user's browser.

Generated by performance advisor bot at iscalypsofastyet.com.

[matticbot]

Caution: This PR affects files in the Editing Toolkit Plugin on WordPress.com
Please ensure your changes work on WordPress.com before merging.

D53351-code has been created so you can easily test it on your sandbox. See this FieldGuide page about developing the Editing Toolkit Plugin for more info: PCYsg-ly5-p2

[dubielzyk]

Looking super good. Here's a few pixel changes:

• Let's make the .wpcom-editor-welcome-tour-frame position left: 16px instead of 40px. And bottom: 44px instead of 40px
• The close and minimize button should only appear once the Welcome Tour is hovered. The buttons should have opacity 0.7 and 0.9 on the button hover. See gif
• The close and minimize button are currently 36px, but should be 32px. The icon within should be 24px.
• Remove the current border and box-shadow on the Welcome Tour and use box-shadow: rgba(0, 0, 0, 0.1) 0px 0px 0px 1px, rgba(0, 0, 0, 0.1) 0px 2px 4px 0px instead
• The components-card__body has a padding of 12px but it should be 16px
• The active step color shouldn't be blue, but rather gray 700 (or equivalent)
• The copy says Welcome to Wordpress, but it should be Welcome to WordPress
• welcome-tour-card__heading should have font-size: 1.125rem not 1.25rem
• The distance between the heading and the text is ~24px, but should be ~16px. Mock

[roo2]

Thanks for the feedback @dubielzyk I was able to address them all, let's make a build of it on monday and upload it to the ephemeral site for testing.

I tried to test the welcome tour in safari but had a few problems:

• I can't seem to get my sandbox to work in safari, my hostsfile generally does work but when I set public-api to point to my sandbox, for some reason I still see the production api in safari... so I wasn't able to test this.
• I tried uploading a build of the plugin to an atomic site but it seems that atomic sites use different logic to determine whether to show the welcome tour, perhaps it doesn't even make sense to show the welcome tour to atomic users since presumably they would be more advanced users already?

I applied a bit of a simple fix for the janky image loading, I just put a fixed height on the image container so that the welcome tour doesn't jump around as images are loading, you might still look into preloading images if you think that's necessary as well.

I had intended to put this behind a feature toggle but we don't actually have access to our calypso feature flags from the editing toolkit plugin, we should find a way to A/B test this, we'll have to look into hat actual A/B testing options we have access to from the ETK plugin...

[ramonjd]

we'll have to look into hat actual A/B testing options we have access to from the ETK plugin...

Maybe checkout what @deBhal and @andrewserong are doing on the premium patterns side of things. See pbmo2S-Ca-p2#comment-1369 and D53680-code

[dubielzyk]

This is great progress. Two more things:

• Let's remove the 1px solid rgb(226, 228, 231) border on the .components-card div.
• This might cause the cut corner look. If that happens lets round the corners on the corners that are affected

[ramonjd]

I can't seem to get my sandbox to work in safari, my hostsfile generally does work but when I set public-api to point to my sandbox, for some reason I still see the production api in safari... so I wasn't able to test this.

I think I figured out why. See pbAok1-1Dh-p2#comment-3502

[ramonjd]

Let's get this in the ETK, even if we're not shipping.

One way to do that would be to create a new directory for this work and copy the files over so we're not modifying the current NUX tour.

Then update the load_wpcom_block_editor_nux() method to conditionally load the new tour.

For example:

/**
 * Load WPCOM Block Editor NUX
 */
function load_wpcom_block_editor_nux() {
	if (
		( defined( 'WPCOM_NUX_WELCOME_TOUR' ) && WPCOM_NUX_WELCOME_TOUR ) ||
		apply_filters( 'a8c_enable_wpcom_welcome_tour', false )
	) {
                // THE NEW ONE! 
		require_once __DIR__ . '/wpcom-block-editor-welcome-tour/class-wpcom-block-editor-welcome-tour.php';
                return;
	}
         // THE CURRENT ONE
	require_once __DIR__ . '/wpcom-block-editor-nux/class-wpcom-block-editor-nux.php';
}
add_action( 'plugins_loaded', __NAMESPACE__ . '\load_wpcom_block_editor_nux' );

So, if WPCOM_NUX_WELCOME_TOUR constant is defined in the sandbox we'll load the new plugin. Later, we'd rely on the a8c_enable_wpcom_welcome_tour filter to control access on production. See D53894-code for an example

Some discussion here:
p1607396394436800-slack-CRWCHQGUB

Let me know if you have any questions!

[autumnfjeld]

@dubielzyk

• Let's remove the 1px solid rgb(226, 228, 231) border on the .components-card div.

Done. Corners look good

[andrewserong]

This feature is looking so good @autumnfjeld!

I've left a comment about a duplicate class name warning in PHPCS because of the duplication of the NUX status controller. I can think of a couple of potential ways of dealing with this:

• If you don't mind the duplication with this class, you could rename it. Or, find a place to keep the shared PHP files between this feature and wpcom-block-editor-nux so it only needs to be defined once (this would be better so that there aren't two attempts to register effectively the same API endpoint). Or,

• Move the Editor Welcome Tour feature to be part of the wpcom-block-editor directory, and share code, which means you could also remove the duplication of the disable-core-nux.js and public-path.js files. The downside of this is that it mightn't be as neat to switch the feature and on off. Because we're enqueueing the one JS bundle, to handle switching features on and off we might need to use a wp_localize_script call to pass a boolean to the JS to flag that the feature is enabled. E.g.

wp_localize_script(
  'wpcom-block-editor-nux-script',
  'wpcomBlockEditorWelcomeTourActivated',
  true, // the boolean value of whether or not the feature is enabled
);

Then, in the JS, you could detect whether or not the feature is enabled by checking window.wpcomBlockEditorWelcomeTourActivated.

Personally I don't mind a bit of duplication at all while we're exploring a new feature, it can make it much easier to try things without having to worry too much about affecting an existing feature, but it can also be a bit tricky when there are collisions (like with the API endpoint). So I think it'd be perfectly valid to keep the two separate if you think it makes sense for the experiment!

[autumnfjeld]

@andrewserong Thanks for all the suggestions!! :)

I think I'm ok with leaving the duplicate javascript files (public-path.js, store.js, etc) because as you said, the state of the NUX and Welcome Tour code is currently exploration.

I fixed the PHP duplication however.

Move the Editor Welcome Tour feature to be part of the wpcom-block-editor directory

I assume you mean wpcom-block-editor-nux directory. This is how I started the work, but we needed to separate the Tour from the NUX to run A/B tests. I think because php is in charge of determining which component to show: apply_filters( 'a8c_enable_wpcom_welcome_tour', false ) . However, now that I think more deeply about this it could have probably been set up differently.....but maybe other ways would have been more complicated.

[andrewserong]

That sounds like a good trade-off to me @autumnfjeld, and nice idea getting wpcom-block-editor-nux to use the file in your PR so you've got a bit more flexibility for this feature 👍

[andrewserong]

I forgot to add: because the other usage of this controller also attempts to register the route, we might just want to test that this doesn’t throw an error anywhere. I think you can safely call to register the same route twice, but we might want to double check (check that it doesn’t throw errors and that the endpoint behaves as we’d expect). The function register_rest_route says that it returns false if it can’t register an endpoint so I suspect it’ll safely silently fail the second time, or just override the first call, which is also fine 🤞

[autumnfjeld]

@andrewserong Thanks so much for pointing this out! Got me to think/learn a bit more in depth about some WP & php concepts.

register the same route twice

If I understand you correctly, the concern is that class WP_REST_WPCOM_Block_Editor_NUX_Status_Controller will be registered twice, once when NUX code loads and again when Tour code loads. However, only one of these will load at a time, it is an either/or situation for A/B testing. This code in full-site-editing-plugin.php decides which to load.

In my sandbox I tested both scenarios and I didn't observe any errors in my /tmp/php-errors file or in dev tools. (Note: Adding define( 'SHOW_WELCOME_TOUR', true ); to 0-sandbox.php file will force the new Tour to show).

Does that address the issue? Or is there anything I'm missing/not understanding?

[andrewserong]

@autumnfjeld perfect, that sounds good to me! And from reading the docs for register_rest_route, it looks like even if it wasn't guarded behind that either/or condition we'd probably still be safe 👍