Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Implement welcome guide modal #18041

Merged
merged 22 commits into from Dec 2, 2019
Merged

Implement welcome guide modal #18041

merged 22 commits into from Dec 2, 2019

Conversation

noisysocks
Copy link
Member

@noisysocks noisysocks commented Oct 21, 2019

Closes #16315.

Implements the welcome guide modal described in #16315 (comment).

guide

What's changed

  • There's a new Guide component in @wordpress/nux which implements the guide modal in a reusable way. This is marked experimental so that we can potentially move this to @wordpress/components in a follow-up PR.
  • WelcomeGuide in @wordpress/edit-post will use Guide to display a welcome guide for the block editor if the user has not previously disabled tips. This replaces all of our instances of the DotTip component. We can potentially move away from using hasDisabledTips in a follow-up PR.
  • There's a new Welcome Guide button in the More menu which allows the user to open the guide again. This replaces the Enable Tips setting in the Options modal.

How to test

Unit and E2E tests are included. To manually test the upgrade process, follow these steps:

  1. On master, open the block editor and ensure that you have dismissed tips.
  2. Check out this branch and open the block editor. The welcome guide should not appear.
  3. Rest your browser's localStorage to simulate being a new user.
  4. Refresh the page. The guide should appear.
  5. Dismiss or complete the guide.
  6. Refresh the page. The guide should no longer appear.

@noisysocks
Copy link
Member Author

@noisysocks noisysocks commented Nov 6, 2019

There's still lots to do here, but it would be good to get some early design feedback 🙂

@noisysocks noisysocks added the Needs Design Feedback label Nov 6, 2019
@enriquesanchez
Copy link
Contributor

@enriquesanchez enriquesanchez commented Nov 12, 2019

Hey @noisysocks! 👋

Happy to help with design feedback. How can I get this to show up on my local install?

@noisysocks
Copy link
Member Author

@noisysocks noisysocks commented Nov 14, 2019

Thanks @enriquesanchez! You can check out the branch and then open the Welcome Guide from the More menu:

Screen Shot 2019-11-14 at 15 16 20

@noisysocks noisysocks force-pushed the add/welcome-guide branch 3 times, most recently from 4dfdc1c to bc79748 Compare Nov 18, 2019
return (
<Modal
className="edit-post-welcome-guide-modal"
shouldCloseOnClickOutside={ false }
Copy link
Member Author

@noisysocks noisysocks Nov 18, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've disabled this to work around an issue where the modal is immediately dismissed on page load because the post's title field receives focus. Let me know if you can think of a better alternative!

{ __experimentalCreateInterpolateElement(
__( 'All of the blocks available to you live in the Block Library. You’ll find it wherever you see the <InserterIconImage /> icon.' ),
{
InserterIconImage: (
Copy link
Member

@aduth aduth Nov 19, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like how you chose to name the property to align with the component name, but in-so-doing it occurs to me whether we ought to have any coding guidelines around the names we choose for these interpolated keys? cc @nerrad

Copy link
Contributor

@nerrad nerrad Nov 19, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is a question best answered by those working more closely with translators.

One of the intents behind the interface is to provide additional guidance to translators on what a tag represents and signal that it shouldn't be translated. With WordPress core in particular, I think generally translators know to leave tags alone (although that has been a smaller subset of tags I think).

I think others might be better equipped to detail what standards we should have. cc @ocean90 , @swissspidy or @akirk , do you have any guidance here?

Copy link
Contributor

@akirk akirk Nov 28, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am huge proponent of "speaking" component placeholders. It's a very easy way to convey to translators what is being substituted here. InserterIconImage sounds good to me.

How and where would be put coding guidelines for this?

Copy link
Member

@gziolo gziolo Nov 28, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like this proposal. Assuming that it's copied to all translations it would work great 👍

For the full picture, there are some drawbacks discussed in the PR which test this new API. The discussion triggered by @johnbillion starts with this comment: #18623 (comment).

Copy link
Member

@gziolo gziolo Nov 28, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@akirk do you suggest that the following:

{ __experimentalCreateInterpolateElement(
	__( 'While writing, you can press <kbd>/</kbd> to quickly insert new blocks.' ),
	{ kbd: <kbd /> }
) }

could be easier refactored to:

{ __experimentalCreateInterpolateElement(
	__( 'While writing, you can press <Shortcut /> to quickly insert new blocks.' ),
	{ Shortcut: <kbd>/</kbd> }
) }

@TimothyBJacobs
Copy link
Member

@TimothyBJacobs TimothyBJacobs commented Nov 19, 2019

Would it be possible for the <Guide /> component to be a part of NUX? This looks like something that'd be awesome to use on plugin admin screens as well. But since <Guide /> is in editPost it'd be difficult to use.


Separately, it looks like #12632 would still be effected by this tips redesign. AFAICT, the close button here is dismissing all guides instead of just the current "guide".

@noisysocks
Copy link
Member Author

@noisysocks noisysocks commented Nov 20, 2019

Would it be possible for the <Guide /> component to be a part of NUX? This looks like something that'd be awesome to use on plugin admin screens as well. But since <Guide /> is in editPost it'd be difficult to use.

Good suggestion! I'll look into this.

@mapk: Do you think a guide component would be useful outside of WP Admin? If so, then I think we should consider putting Guide and/or GuideModal into @worpdress/components so that we get to use the existing infrastructure there e.g. storybooks.

Separately, it looks like #12632 would still be effected by this tips redesign. AFAICT, the close button here is dismissing all guides instead of just the current "guide".

Thanks for pointing me to #12632. I'll look into moving away from areTipsEnabled(). My preference is to make Guide a dumb component and leave it up to the plugin developer to decide when to show it.

@mapk
Copy link
Contributor

@mapk mapk commented Nov 20, 2019

@mapk: Do you think a guide component would be useful outside of WP Admin? If so, then I think we should consider putting Guide and/or GuideModal into @worpdress/components so that we get to use the existing infrastructure there e.g. storybooks.

YES! Adding this to @wordpress/components sounds reasonable to me. Allowing other developers to use it could be amazing.

@mapk
Copy link
Contributor

@mapk mapk commented Nov 20, 2019

I really like how this is shaping up! Great work. Here's some design feedback:

1. First image needs to be centered better.

The webpage in the graphic feels like it's not quite centered. Even the blocks in the webpage don't look centered.

Screen Shot 2019-11-20 at 8 34 45 AM

2. First two graphics should be equal width.

I think this may help visually if both graphics in the first two images are equal width within the blue container.

1

3. Should we capitalize certain things?

"Block Editor" or "Block Library" seem like proper nouns. For example, we capitalize Block Library in the sentence, but not in the heading of the third screen.

4. Second screen text addition

Should we mention that you can move the block toolbar to be fixed at the top of the screen for less visual distractions?

5. This icon can probably use some visual cleanup.

Also lets make the triangle white to match the popover graphic too. Right now it's grey.

Screen Shot 2019-11-20 at 9 29 02 AM

I think these last few changes will dial it in beautifully.

@enriquesanchez
Copy link
Contributor

@enriquesanchez enriquesanchez commented Nov 20, 2019

Hey @noisysocks! This is looking great! 🎉

Visuals

Would it be possible to align the close button so it has the same space around like the previous and next/get-started buttons?

Screen Shot 2019-11-20 at 16 06 24

I also noticed that the hover state of the page control buttons looks a bit off. It looks like the right border is missing half a pixel (I'm on a retina display).

Screen Shot 2019-11-20 at 16 23 17

Accessibility

I was able to interact with the welcome guide using only my keyboard 👍

I also did a quick test with Voice Over and had a couple of issues:

The page control buttons could use an aria-label so it's communicated to assistive technology what they're for. I was expecting to hear something like "page 1 of 3".

I'm thinking these could be grouped on a ul so they're part of the same group. Following suggestions on how to markup content sliders from the Inclusive Components pattern library, it could be something like:

<ul aria-label="Welcome guide controls">
    <li><button aria-label="Page 1 of 3"></button></li>
    <li><button aria-label="Page 2 of 3"></button></li>
    <li><button aria-label="Page 3 of 3"></button></li>
</ul>

I don't think the images need an alt description, because the accompanying text does a good job of describing each page/topic. That being said, they should have an empty alt = "" so that they're ignored by AT.

Overall, this is looking great! Let me know what you think of my comments and suggestions.

@enriquesanchez
Copy link
Contributor

@enriquesanchez enriquesanchez commented Nov 20, 2019

@noisysocks where are you getting the images from? Let me know if you need help with Mark's suggestions on alignment and size.

@noisysocks
Copy link
Member Author

@noisysocks noisysocks commented Nov 21, 2019

Thanks @mapk and @enriquesanchez! I'll work through your suggestions.

@noisysocks where are you getting the images from? Let me know if you need help with Mark's suggestions on alignment and size.

I would absolutely love it if you could update the images for me! I got the SVGs from @jasmussen, who I think exported them from the 'Tips Iteration' project in the WordPress.org Figma team.

@enriquesanchez
Copy link
Contributor

@enriquesanchez enriquesanchez commented Nov 21, 2019

Hey @noisysocks! (I never get tired of your username 😃)

Here are the new SVGs with Mark's suggested changes:

illustrations.zip

@enriquesanchez
Copy link
Contributor

@enriquesanchez enriquesanchez commented Nov 21, 2019

Wait, I noticed the add block icon on 'illustration 3.svg` was still showing some weird artifacts.

Here's a cleaner version:
illustration 3_.svg.zip

@noisysocks
Copy link
Member Author

@noisysocks noisysocks commented Nov 22, 2019

  1. First image needs to be centered better.
  2. First two graphics should be equal width.
  3. This icon can probably use some visual cleanup.

👍 I updated the images in d8cee82. Thanks for fixing those up @enriquesanchez!

  1. Should we capitalize certain things?

👍 I capitalised 'Block Editor' and 'Block Library' in 745fdd4.

  1. Second screen text addition

I'll defer to you all on this one. Let me know what you'd like the copy to be and I can update it.

Would it be possible to align the close button so it has the same space around like the previous and next/get-started buttons?

I updated the alignment in 47c2879, though I wonder if doing this makes the X button look too much like 'content' instead of 'chrome'? Let me know what you think.

Screen Shot 2019-11-22 at 11 42 11

The page control buttons could use an aria-label so it's communicated to assistive technology what they're for. I was expecting to hear something like "page 1 of 3".

👍 I updated the page controls to use the markup you suggested in 92e1773.

I don't think the images need an alt description, because the accompanying text does a good job of describing each page/topic. That being said, they should have an empty alt = "" so that they're ignored by AT.

The images already have an empty alt="" attribute.

@noisysocks
Copy link
Member Author

@noisysocks noisysocks commented Nov 25, 2019

Separately, it looks like #12632 would still be effected by this tips redesign. AFAICT, the close button here is dismissing all guides instead of just the current "guide".
Thanks for pointing me to #12632. I'll look into moving away from areTipsEnabled(). My preference is to make Guide a dumb component and leave it up to the plugin developer to decide when to show it.

Let's look at making the welcome guide use something other than areTipsEnabled in a separate PR. There are some details to consider there and I want us to have the opportunity to properly think it through. We also need to consider whether or not we want to maintain or deprecate the @wordpress/nux package. #12632 can track that work.

YES! Adding this to @wordpress/components sounds reasonable to me. Allowing other developers to use it could be amazing.

I've left Guide in the @wordpress/nux package for now because it requires isViewportMatch to determine whether or not to display the 'Get started' button inline with the content. Let's consider moving Guide to @wordpress/components in a follow-up PR—I've marked Guide as experimental for now so that we can do this.

@noisysocks noisysocks marked this pull request as ready for review Nov 25, 2019
@joedolson
Copy link

@joedolson joedolson commented Dec 6, 2019

The modal is not labelled. This is in part a problem with this modal, but should probably be corrected in the component: the Modal component allows the component to be misused.

We should enforce a label for the modal element with role=dialog within the e2e tests, because all modals must be labelled. Additionally, the modal component should enforce 'role="document"' on the content of all modal dialogs. This isn't strictly required on all modals, but the component can't know what type of content a modal will contain, this will give the best overall experience.

There are usability problems with having this modal open automatically on page load.

  1. As it is (unlabeled), it's going to be confusing for some users.
  2. It disrupts the flow for users who wish to use Gutenberg immediately.
  3. Users who reflexively dismiss modals will not easily be able to get it back.

One possible way that this could be made available is to add a prominent button for users to launch the Welcome Modal if they are detected as new Gutenberg users. The modal, in that case, should have two cancel actions: one that simply closes the modal, and one that dismisses it persistently.

As a second issue, the method for assessing whether a user is "new" to Gutenberg is significantly flawed: the usage of local storage for this means that a user will be new on every device they use, on every browser they use, and on every new site they launch. Secondarily, because the detection appears to be based on the positive presence of 'modal dismissed' setting in local storage, it will essentially be impossible to permanently disable it; anytime the local storage is flushed it will come back. (See #15105)

}
}

&__container {
Copy link
Member

@aduth aduth Dec 17, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While I think this convention certainly makes things more concise, in practice I find it adds difficulty to a very common use-case of searching for a class name in the codebase. To try to search for "components-guide__container" would not yield this as a result.

While it requires a couple more characters to type, I would personally advocate to use the fully expanded form in source:

.components-guide__container {

// Focus the button on mount if nothing else is focused. This prevents a
// focus loss when the 'Next' button is swapped out.
useLayoutEffect( () => {
if ( document.activeElement === document.body ) {
Copy link
Member

@aduth aduth Mar 2, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In #20594, I am encountering an issue where we make certain assumptions about what it means for "no focus" to exist. It appears that the value of activeElement may differ depending on browser:

When there is no selection, the active element is the page's <body> or null.

https://developer.mozilla.org/en-US/docs/Web/API/DocumentOrShadowRoot/activeElement

I mention it here, since this may not cover all focus losses, notably those in Internet Explorer. Specifically, this condition is only checking for the first of these two possible "no active element" scenarios.

image

It might be something where we want to provide some utility, e.g. wp.dom.hasActiveElement, since it seems to be an easy issue to overlook.

Edit: I confirmed that there is a focus loss which occurs when reaching the last page of the guide in Internet Explorer:

image

Copy link
Member

@aduth aduth Mar 2, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fix at #20599

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment