Extend Dashboard Sharing feature tour to include settings interface

Feature Description

In #5328, we added a basic feature tour for dashboard sharing which informs an authenticated admin about the added ability to share the dashboard with other users but does not elaborate on how to use it.

This issue is about extending this tour with additional steps to walk the user through the sharing settings interface and better explain how to share the dashboard and or delegate sharing management.

---

Do not alter or remove anything below. The following sections will be managed by moderators only.

Acceptance criteria

The feature tour for dashboard sharing should be extended as follows:

• The tour should get additional steps to walk the user through the sharing settings interface
  • A second step should be added:
    • Title: Manage view access for other roles
    • Body: Grant access to the view-only dashboard for each service for the specific roles you want. Users will see the Site Kit dashboard with only the services that have been shared with them without needing to sign-in with Google.
    • On display, the dashboard sharing settings modal should be toggled open
    • Focus: “Who can view” column
  • A third step should be added but only if the site has multiple admins (otherwise this column will not be displayed/relevant)
    • Title: Share management with other admins
    • Body: By default only the user who connects a service can control who it is shared with. This setting optionally lets these users allow any other admin signed in with Google to manage the roles a service is shared with.
    • Focus: “Who can manage” column
  • On dismiss/completion the dashboard sharing settings modal should be closed
• If the user dismisses the feature tour on the first step (showing settings button) they should still see the remaining tour steps when viewing the sharing settings interface for the first time (i.e. on demand)
  • Dismissing on step 2 or 3 should dismiss the full tour as usual

Note: these could technically be separate tours with shared steps, etc – it is not strictly required that everything is defined in a single tour.

Implementation Brief

• Update DashboardSharingSettingsButton to use the CORE_UI store for the dialogOpen state (e.g. dashboardSharingDialogOpen)
• Update _googlesitekitDashboardSharingData to include the value of hasMultipleAdmins from Has_Multiple_Admins
• Define a new dashboardSharingSettings feature tour
  • The first step should be defined as the “second” step in the ACs
    • The target should use .googlesitekit-dashboard-sharing-settings__main .googlesitekit-dashboard-sharing-settings__column--view to highlight the first row’s user role select control
  • If _googlesitekitDashboardSharingData.hasMultipleAdmins is true, the second step (corresponding to the “third” step in the ACs) should be included/appended
    • The target should use .googlesitekit-dashboard-sharing-settings__main .googlesitekit-dashboard-sharing-settings__column--manage to highlight the first row’s sharing management control
  • The contexts for this tour should be omitted because it should not be triggered automatically by view context, but only by its inclusion in the dashboardSharing tour or on its own, on-demand
• Update the dashboardSharing tour to import the new dashboardSharingSettings tour definition, appending its steps to its own
  • Define the callback function to respond to the tour events appropriately:
    • If transitioning to the 2nd step, set the dashboardSharingDialogOpen state to true
    • If transitioning to the 1st step, set the dashboardSharingDialogOpen state to false
    • When exiting the tour, ensure dashboardSharingDialogOpen is set to false again
    • Keep track of visited tour steps, if step 2 was reached, dismiss the dashboardSharingSettings tour when exiting the tour

• Update feature tour infra to work similar to user surveys
  • Introduce a new initialState.currentTour property, which should hold the definition of the current tour being shown
  • Introduce a new selectors.getCurrentTour (no arguments) that returns the state.currentTour
  • Introduce a new actions.receiveCurrentTour action that sets the state.currentTour
  • Introduce a new actions.triggerTour which takes a tour object and receives the currentTour if there is none currently set
  • Introduce a new actions.triggerTourForView(viewContext)
    • If feature tours are currently on cooldown (areFeatureToursOnCooldown), the action should return early and do nothing else
    • Otherwise, it should take the given viewContext and check all the tours as we do now in resolvers.getFeatureToursForView, and dispatch triggerTour with the first tour that qualifies
  • Introduce a new actions.triggerOnDemandTour(tour) that checks the given tour’s requirements (below) before dispatching triggerTour(tour):
    • The tour should not be dismissed
    • Its own checkRequirements function should return true
    • It should not be affected by tour cooldown
  • Update FeatureTours to source the tour it passes to TourTooltips via the new getCurrentTour selector only
    • A new onMount effect should be used to dispatch actions.triggerTourForView(viewContext) to preserve the current behavior of invoking tours for the current viewContext
  • selectors.getFeatureToursForView and its resolver should no longer be necessary
  • Update actions.dismissTour to unset state.currentTour if the given tour slug matches the current tour’s slug
  • Update DashboardSharingSettingsButton with a useEffect to triggerOnDemandTour with the dashboardSharingSettings tour object when the dialog is opened
    • Note the dashboardSharing tour will essentially trigger this as part of the changes here but the secondary triggerTour will have no effect because a currentTour will already be set/running

Test Coverage

• Add tests for the new actions and selectors added to the core/user data store.
  • selectors.getCurrentTour
  • actions.receiveCurrentTour
  • actions.triggerTour(tour)
  • actions.triggerTourForView(viewContext)
  • actions.triggerOnDemandTour(tour)

• Update tests for actions.dismissTour
• Remove tests for getFeatureToursForView

QA Brief

This issue extends the existing feature tour for dashboard sharing with additional steps to cover the sharing settings.

• For a site with a single admin, the tour will have 2 steps (1 extra)
• For a site with multiple admins, the tour will have 3 steps (2 extra)
• If the user sees the main tour and dismisses it before they get to the last step, they will see a secondary feature tour when the sharing settings are opened (even if they just saw the first)
  • This secondary tour will only have the extra 1-2 steps as mentioned above
  • They will always see all the extra steps in this tour, not just the ones they didn’t see from the first
• It is possible for a user to see a different tour before the main DS tour (enabling the cooldown) and then trigger the on-demand DS settings tour without seeing the first as it is currently. This is probably an edge case we don’t need to worry about too much but also could be addressed if we want to with out a large additional effort

Changelog entry

• Extend the Dashboard Sharing feature tour to include steps for the settings interface.

[eclarke1]

Just a note regarding the background colour of the feature tour, I have added a comment here https://github.com/google/site-kit-wp/issues/5254#issuecomment-1178703818 for @aaemnnosttv to kindly review and add today please.

[aaemnnosttv]

I’m not a big fan of “overloading” the context argument with a “magic” ON_DEMAND viewContext. This isn’t a real value and realistically ends up representing a feature-tour that isn’t dependant on a viewContext, but instead is triggered by something else entirely.

@tofumatt, I was thinking we might want to be able to use a given tour on load (as it is now) or on-demand in some cases. The current tour requirements check requires tour.contexts but I think this shouldn’t be needed given the approach outlined here checks the requirements separately for an on-demand tour. I think the addition

I’d rather us add a new property for feature tours like showOnDemand and make viewContext for a feature tour optional in the presence of the showOnDemand property. Functionally it would behave the same, but that way we don’t have any magic values.

Yes I thought about that as well, but I think such a property shouldn’t be necessary as on-demand tours are checked differently as defined.

There’s mention of extending a feature tour with data from another based on conditions, but I’m not clear on why that’s needed. I’d think we’d have another feature tour triggered when opening the Dashboard Sharing modal/dialog, and clicking “next” on the “first” feature tour (eg. the first “step” of this multi-tour tour) would open the Dashboard Sharing modal/dialog.

The idea is that in the user’s experience, it’s only one tour so long as they see both parts. Implemented as separate tours that are triggered seamlessly, the experience is unintuitive because you’d first see a tour with one step and then immediately see a second tour with one or two steps. This way, the user sees (and interacts with) the first tour as a more comprehensive tour from the beginning, and is able to navigate back and forth to/from any step until it is dismissed (like others). As separate tours, they’d be stuck in the second, unable to go back to the first once triggered. This is also why the ACs call for a second and conditional third step to be added to the first tour rather than simply triggering a separate tour immediately after dismissing the first.

That’s why the first is more of a composite tour – we only show the settings part of it on demand if they don’t reach that part of the tour in the first.

I’m a bit confused as the proof-of-concept PR doesn’t look anything like the IB from what I can tell, but I’m going to check out the PR and see how it works.

The current IB is a bit different and came out of conversations I had with @jimmymadon last week, but he didn’t have time to update it before he left which is why I’ve taken over here 😄

---

I’ve updated the IB to remove the special ON_DEMAND context, but the rest should be good to go I think. Let me know if you have any other questions 👍