Onborda PR

[alexc-harrap]

Hi @uixmat

I have been building off of your package (thanks for this!) to add some features that we needed for our use case. It is a large PR and does contain some breaking changes so not expecting it to be approved, but creating a PR in case you would like to copy some of the enhancements I have added even if you reject the PR.

Breaking Changes

• <Onborda /> no longer has steps : Tour[]. This has been moved up to <OnbordaProvider /> and called tours: Tours[].
  • This is so OnbordaContext has access to every tour and its steps to allow a new useOnborda function of setStep which can switch to any step in the current tour, not just the previous or next.
• Step.prevRoute and Step.nextRoute have been deprecated in favour of a single Step.route defined per step. This is to ensure when switching to any step, the correct route can be navigated to.

Added new optional TourCard

The TourCard is a secondary card displayed in addition of the StepCard on the overlay. The TourCard is intended to show details of the current tour. Eg the todo list of steps.

Added optional Step.interactable = false

Each step can now block or allow interaction with the focused element on a step-by-step basis. EG if the step is part of a setup tour and you point the user to an input for setting their organisation name for example, they can fill that in while the overlay is still active. But if you want to just show them around the site without them changing the current route, then it can be set to false.

Added useOnborda.completedSteps[]

completedSteps is a Set of indexes. Once a step is shown or conditions met (see below), it is added to this Set automatically. This allows the TourCard to keep track of which steps have been 'completed' and allow showing a checkmark against the step for example.

Added optional Step.isCompleteConditions()

isCompleteConditions is a client function that is bound to an event listener on the focussed element on click, input and change. The Element is then passed to this function for custom conditions to be applied before the step is added to the completedSteps Set. EG if the focused element is an input field, the isCompleteConditions function can check the value is valid before marking it as complete.

Added optional Step.onComplete() callback

onComplete is a callback called whenever the step is marked as completed. This can be used to store the state of the step server side.

Added optional Step.customQuerySelector()

I found while using Step.selector that sometimes with UI libraries, the element you can set the ID on is within other divs, causing the pointer to be offset. This allows for getting the selectors parent Element for example.

Added optional Tour.initialCompletedStepsState()

initialCompletedStepsState is a Promise<boolean[]> that is called when a tour is started. This allows fetching the initial completed steps state from a server action. It should return a boolean array the same size as the Tour.Steps array.

Added [key: string] to Tour and Step Objects

[key: string] is a way to allow the user to provide any additional data or flags they wish to use in their TourCard or StepCard making it easier to customise per step or per tour.

Added optional OnbordaProvider.activeTour

activeTour is way to set an initial active tour on load without having to call startOnborda or setTour. This can be useful for Setup tours where you would want the tour to be forced on until the user has completed it.

I have created a demo codespace on my github showcasing the TourCard: https://github.com/alexc-harrap/Libresoft-Onborda-Demo

[Qodestackr]

Is adding a global context the best way out ?

[Jkroeger123]

this is great, thanks for putting this together!

[uixmat]

Hey @alexc-harrap - thanks so much for all your work here, some really good changes! I'm sorry for such a slow response speed, i've just started working at Prisma with no time-off between so its been a hectic couple of months!

I'm implementing some of the changes bit by bit right now!