React-joyride: V2 roadmap

[gilbarbara]

Hello!

The top requirements are:

• eliminate the complexity of the source code
• handle all positioning and z-index problems
• be able to add new features easily
• improve UI tests (using cypress)

And most of them came from implementing the tooltip manually including positioning, which is too much. So I've published a new package react-tooltips that will handle all this heavy lifting using popper.js.

This leaves this package to deal with its primary responsibility: manage the tour.

Tasks

Tour state

• [x] must run outside the react component with some sort of state machine
• [x] exportable actions: next, prev, go, start, stop, restart, reset
• [x] add listeners to state updates (sync with the react component)

Main

• [x] sync state with the component state
• [x] trigger callback when state changes
• [x] use react-tooltips with a custom component for the tooltip and the default beacon as children

Componentization

• [x] add constants: actions, events, lifecycle, status
• [x] add Step component to render Tooltip/Beacon
• [x] Tooltip will render the default tooltip UI and handle custom components
• [x] Beacon will render the default beacon UI and handle custom components
• [x] add Overlay component and test rendering it with ReactDOM.Portal

Step Parser

• [x] check if the passed options are valid (type, content, etc)
• [x] won't check if the selector is mounted

Extras

• [x] hole positioning and tooltip move animation for fixed steps
• [x] implement showProgress and pass size to render props
• [x] add support for server-side rendering
• [x] implement keyboard focus manager
• [x] Accept steps without a target? #279 (Can use the "body" as a default)

Props

New

• [x] beaconComponent - will be called with render props
• [x] tooltipComponent - will be called with render props
• [x] offsetParent ['body'] - the parent element to get target's dimensions/position.
• [x] tooltipOptions - options to be passed to react-tooltips

These props will include props collections for each element (next, back, ...) with aria properties and such.

Renamed (breaking)

• [x] disableOverlay [false] -> disableOverlayClicks [false]
• [x] keyboardNavigation [true] -> disableCloseOnEsc [false] - the space, return and tab keys are now controlled with tabIndex
• [x] scrollToSteps [true] -> disableScrolling [false]
• [x] showBackButton [true] -> hideBackButton [false]
• [x] showOverlay [true] -> disableOverlay [false]
• [x] showStepsProgress [false] -> showProgress [false]
• [x] tooltipOffset [30] -> tooltipOptions.offset [15]
• [x] type ['single'] -> continuous [false]

Removed (breaking)

• [x] autoStart (use the disableBeacon prop on the first step)
• [x] offsetParent
• [x] resizeDebounce
• [x] resizeDebounceDelay

Issues

Features

• [x] step options can override tour options (#170)
• [x] additional placements (#279)
• [x] inline styles – global and per step (handles #144)
• [x] hide beacons – global and per step
• [x] refactor the hole style preferably without box-shadow (#152)
• [x] custom components for the tooltip UI (#300)

Bugs

• [x] positioning and z-index for absolute/fixed elements (#124)
• [x] Accesibility and keyboard navigation (#101)
• [x] keyboard events (#273)
• [x] Can't use components for step's content (#265)

If you ever had problems with tooltip position before, can you please try react-tooltips and let me know if it works for your setup?

[marcandrews]

1. Use redux for state management. If the parent app is not using redux, joyride will create a store to use internally; otherwise, it will use the the parent app's store.
2. react-tether might be a better solution than react-tooltips.

[gilbarbara]

@marcandrews
I don't see how it's possible for a component to use redux without the user modifying its core app. Do you have an example of this setup?

Why react-tether might be a better solution?

[gilbarbara]

@marcandrews
BTW, tether is deprecated and they recommend to use popper.js instead.
I've looked at it while I was researching options to handle the tooltip positioning...

[marcandrews]

react-redux-form can use it's own redux store, but I can think of a better way to implement: if a store is present in context, use that instead; if not create the store and the reducer and use that instead.

popper.js looks promising. My main concern is having to wrap our targets; or can we still target by a selector?

[gilbarbara]

Cool, but I think adding a redux store is too much.

This component is about tours while react-redux-form has it in the name...
I'm thinking about using some sort of machine state in V2 but the state is not that complicated.

No, there no need to wrap anything, not even with react-tooltips, just use the target props.
BTW, react-tether is a "React wrapper around Tether from Hub Spot" 🙃

[gilbarbara]

@marcandrews There will be breaking changes since I'm ditching SCSS styling but the steps props will basically have the same shape and function.

In the react-tooltips demo if scroll down to the custom targets, you will see the same beacon/tooltip styling used here, and this component will wrap those beacons under the hood. Btw you can use custom beacons too!

[marcandrews]

Sweet.

I really think we should use Redux. It will be quite powerful in the end, and even more powerful if the parent app is using Redux as well. We won't have to pass around a reference to the joyride instance to control the walkthrough externally, and and the parent app we can listen for actions dispatched by joyride.

[DavideMontersino]

Hi! Thinking about forking this library because I immediately need some features.

Let me share my thoughts.

Redux

I am using redux too with Joyride but I think it's a bad idea to tie the two library together.
Not everyone uses redux or is willing to install redux just to use this library.

It's better to instead provide an example with redux, or maybe add a higher-order component using redux.

Other features

• not able to remove buttons that I don't want (close button or next button)
• sometimes I want the 'next' action to happen when the click through hole happens instead
• I want to be able to get hole:click event also if the overlay is disabled (I don't want the user to be able to close the tutorial - I just want him to be able to progress if he clicks on the hole)

This is the reason I need these things:
I want to create a "walk through" through my application, so I wanted to be able to 'tie' the user to a linear flow, performing a task from start to finish - being able to exit the tutorial only by finishing it or explicitly skipping to the end.

I will fork now and maybe add some of these features and open a PR if you think it's worth it!

[marcandrews]

The end user does not have to be aware of the presence of redux. If they are not using redux, joyride will create a store and reducer for use internally. If they are using redux and want power granular control of their walkthroughs, they provide the store (and reducer) from the parent application.

Redux could solve all your other requirements too. I have the same requirements and right now, I am storing joyride actions (next, previous, reset) in an array in state, and then mapping that state to my joyride container component. When there is a new action, I call the corresponding joyride instance method within the componentWillReceiveProps lifecycle method.

If want to do something like have the walkthrough progress when the user completes a certain action (instead of when they click next in popup), I need side affect management to:

1. wait for the user action
2. wait for the target to be rendered (if needed)
3. dispatch my joyride next action

All of this would be much easier if the library was using redux natively.

If the end user is not using redux, we can still have joyride instance methods that dispatch the corresponding actions within the library.

At the end of the day, the decision to use redux is a big one and should not be made without careful consideration.

[gilbarbara]

@marcandrews

Adding redux is not something I'm considering for this new version, as it would be an epic change and impact the development of V2 considerably.
If you have other ideas on how to work with Joyride's lifecycle without redux (hooks, callbacks, a plugin system or whatever) let me know.

You could solve your problem but it will cause trouble in other configuration with MobX, GraphQL, Gatsby and a few others libraries that handle the state and I'll never have time to deal with.

[gilbarbara]

@DavideMontersino
You could solve some of these problems with the style property in the step or changing it globally with SCSS.
The hole only exists when the overlay is visible, so I'm not sure what you meant.

Anyway, feel free to fork and modify to your needs. If you need to further discuss this, please open a new issue.

[marcandrews]

How about custom renderers for step components? For instance, you can provide your own next button component.

[consultwithmike]

@gilbarbara I would like to request a couple features:

1. The ability to show multiple beacons at the same time in a "single" beacon setup (if this is already possible accept my apologies and maybe provide some guidance). This would be very useful in our application because then the user could see numerous other targets we want to highlight and they can click them at will.
2. The ability to render tooltips continually on the same target. The use case for this one can be seen by clicking the "Make a Song" button on https://www.musiquest.com/. This is the application that I'm building that uses this library. You'll notice I had to add "Success" tooltips in between instructions for adding notes because I couldn't just move from adding a single note to adding a longer note. As you can see, unlike some of the example you may have mentally, our entire application operates in a single frame regarding the joyride. Maybe this will better explain why I requested it in another issue.

[gilbarbara]

Hey @consultwithmike

I've thought about multiple beacons before but discarded the idea because it falls out of the main purpose of this library: "Create walkthroughs and guided tours". This would break the whole sequential flow of the steps and it only adds complexity to what is supposed to be a simple process.
You can achieve that using individual tooltips and manage the status of each one by yourself.

I'll change how it handles steps in the next version so you could use the same selector for multiple steps.

[consultwithmike]

Thanks a lot @gilbarbara for being willing to drop in the same selector for multiple steps! Also, thanks for the guidance on multiple tooltips, I'll be pulling in that library to doing so!

[gilbarbara]

I think that react-tooltips is mature enough to be used as a replacement for the code I've been using and I've finally started working on V2. 🎉

[gilbarbara]

Ok, first alpha is done! Check out the V2 branch.
You can even play with it with npm i react-joyride@next

[erikrenberg]

It seems that npm says that 2.0.0-1 is the latest version without me specifying @next (my package.json says "react-joyride": "^1.11.3",). Is this as intended?

[gilbarbara]

@erikrenberg sorry, late night deploys. The latest tag is fixed @ 1.11.4

[mplungjan]

Hi Gil,
We are looking to use the very slick looking JoyRide and are looking for two things right now:

1. custom beacons (perhaps a simple question mark icon)
2. show all step beacons at once, giving the user the possibility of taking the tour (which could turn all beacons off and start the tour) or just click directly on the beacon over the subject(s) they want help with

[gilbarbara]

@mplungjan
you will be able to use custom beacons in v2.

[mplungjan]

Very good :) thanks
On Fri, 9 Mar 2018 at 00:10, Gil Barbara [e-mail] wrote:

@mplungjan https://github.com/mplungjan
you will be able to use custom beacons in v2.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/gilbarbara/react-joyride/issues/291#issuecomment-371656743,
or mute the thread
https://github.com/notifications/unsubscribe-auth/ABXevPbQFujipszjcpFGSkRGLkmPKWyKks5tcbpdgaJpZM4RNJtR
.

[lcvbeek]

Are there plans for decreasing the bundle size for v2?
The current alpha is 24kB minified and gzipped, as opposed to the 9.8kB for the latest 1.11.4 release.. Using react-tooltips adds 13.5kB, while a simple library such as react-tipsy is a bare 1.8kB. Bundle sizes are becoming increasingly important...

[gilbarbara]

@lcvbeek Not right now...
The culprit is popper.js which I needed to fix over 100 issues with positioning.

Feel free to suggest an alternative within react-floater repo that could handle all the needs it has.

[monsieurnebo]

Hello,

The documentation seems to indicate that the current version is the v2 (e.g. "migrate from v1.x", no more v2 branch, ...), but the npm package is still v1.x.

Did I miss something? 🤔

[gilbarbara]

@monsieurnebo yes. It's on the README.

npm i react-joyride@next

[monsieurnebo]

I'm already using the v2 via @next, but I don't understand what is the official current version.

The next stands for "next version", so we're currently in v1 if I'm right. But as I said, the documentation is already speaking about migration from v1, etc.... So I'm a bit confused.

[Martinsos]

Hi, just wanted to check what is the current status of v2? I see that most of the features have been completed, are we to expect big changes before it becoming stable or are we almost there?
Thanks a lot!

[dcworldwide]

I just upgraded to latest stable following the migration docs, only to release we aren't at version 2 yet. Wasted 30 minutes. Fun times.

[dcworldwide]

Was expecting master == 1.x and either a 2.x or a next branch with alpha/beta code changes/migration docs

[gilbarbara]

@Martinsos the API won't change anymore. I'll try to fix the issues asap and release it

[ellej16]

@gilbarbara Hi, a couple of questions:

• would disableOverlayClicks just disable the clicks on the overlay- as the boolean says, or would behave the same as the previous disableOverlay and remove the overlay altogether?

• I read on the description that you're exporting the Overlay as a component, would that mean it would be customizable as well now (i.e. adding a skip button to the overlay seems a valid use case for this, or a handleOverlayClick functionality seems good)?

• Where can we try the new api out / release date ? Tried using next on codesandbox to no avail.

Also, thank you very much for this awesome project!

Cheers!

[rezaabedian]

Hi @gilbarbara like many here I also developed against v2.0, but just realised it’s not officially avialable on npm. Is there any indication when it will no longer be available just at @next?

[catncradle]

Bumping this thread.
Really loving the v2.0 and it works great! The public npm version does not work out of the box for me, so I was wondering if there were any update on the release date since it's been a few months since the last post?

[jkjustjoshing]

@gilbarbara thanks for your work on this!

I just wanted to communicate the confusion that the reference to v2 in the docs just caused me, even though v2 does not exist. I highly recommend keeping the v1 docs live in the master branch until v2 is merged to avoid confusion.

I don't want to used an unreleased version not pegged to a single commit, so v2 right now isn't usable for me.

[gilbarbara]

V2 will be released tomorrow!
Thanks for your help and patience.

[dcworldwide]

Awesome @gilbarbara

Excited to upgrade. We use it for our new user onboarding. We have ~35k users who have had the pleasure of your user tour lib.