feat(useStepper): new function

[innocenzi]

useWizard

Description

This is a utility function that helps building step-based wizard components. This is something that I found myself doing over and over in our apps (at least 3 times), and I think it's quite useful.

The declaration of the steps is done via an array of strings steps of arbitrary types. The composable returns a few functions and computed variables that are useful for navigating through the steps.

For instance, the goToPrevious and goToNext function check if we can actually go back or forward. Computed variables like isFirst or isLast or current help determining what to display. To display the component for the current step, one can use currentStepIs('step name').

I'll happily review the wording of every function and variable, but they are all useful ones that I actually used in the real world.

---

What is the purpose of this pull request?

• Bug fix
• New Feature
• Documentation update
• Other

[michealroberts]

@innocenzi I'd maybe rename this to "useStepper" or "useStepperWizard" ... what do you think?

[innocenzi]

Sounds good to me yes! I'll do this on monday or earlier if I have the time this week-end.

[innocenzi]

I think useWizard is more widely used and would be easier to find for someone looking for this composable, useStepper is also fine by me so I went ahead and renamed it

[antfu]

I like this idea in general. But I would try to make it minimal as possible.

[antfu]

I would prefer to have this check on usage.

[innocenzi]

I'm sorry, I don't understand. On usage of what? To clarify, goTo allows to jump to a step without any check, while backTo allows to go back to a previous step if it has been completed.

I needed this feature when trying to allow to click on the step names, but only when it has been done, as you can see on the demo:

<button :disabled="todo(step)" @click="backTo(step)" v-text="step" />

[antfu]

It would feel a bit weird to me that:

const s = useStepper([1,2,3,4])
s.goTo(2)
// ...
s.backTo(3)
// and s stays on 2

In your case, the disabled already serve as a guard for it.

[innocenzi]

But backTo can be called from somewhere else than a button and in that case, disabled wouldn't guard it. Also a button's attribute is easier to tamper with than the code directly.

If you think it's weird maybe you just need to use goTo in such a situation? I designed backTo with the guard idea in mind, and if it's removed, the function becomes useless in favor of goTo. But in every wizard I made in my recent apps, this specific function was useful.

Maybe we can rename backTo with a name that would be less confusing?

[antfu]

Yeah, what I mean is the guard should be done on userland when calling goTo. Since there is only one line of addition in backTo, the trade-off of saving one line but introducing an additional abstraction layer that users/readers need to understand is a bit less worthy to me. I'd suggest we remove it, and let users define it when needed.

[innocenzi]

I understand - I removed it.

That being said, I still think this function is very useful, since I used it in all my wizards without exception - and I updated the demo code to show you how an userland backTo would look like, I think it's not the best DX-wise.

But I respect your decision if you still think it's not needed!

[antfu]

Suggested change

	export function useStepper<T extends string>(steps: readonly T[], initial?: T) {
	export function useStepper<T>(steps: readonly T[], initial?: T) {

Can we have it arbitrary? I might want to use objects.

[innocenzi]

Yes I don't see a reason why it should only be strings. I use that mostly but you're right that objects can be useful. Also added basic tests for that.

[innocenzi]

@antfu Do you have a suggestion of how to use currentStepIs and other functions with objects? Partial match?

[innocenzi]

I followed-up in #1754 with a better implementation. Closing this because the review is stale.