Stepper component

[Josh-Cena]

Requested on Canny: https://docusaurus.canny.io/feature-requests/p/stepper-component

Would be nice to have a stepper component (like https://mui.com/components/steppers or https://garden.zendesk.com/components/stepper, but more integrated with Docusaurus and its theme) for step-by-step instructions.

I think that makes sense

[slorber]

So it would be a component similar to the Tabs with a React/MDX API?

Why not, but I'd like to understand better the motivations of the user to request this component in Infima + core, considering it can be implemented quite easily in userland

It would be nice to have a userland implementation first to see it in action in production on a real case before adding this as a first-class feature.

[Josh-Cena]

Most likely, yes, we would implement the styles in Infima and provide a convenient way to write it in React.

The motivation is to achieve consistent styling. We had numerous past requests for form elements which are probably out of scope, but since this one is static, I think it's okay.

[petrbroz]

Thanks guys! Here's the motivation for this kind of component: when working on a step-by-step tutorial that's made of a larger number of screenshots, and very little text content (for example, like here: https://petrbroz.github.io/forge-samples-docs/docs/intro/#create-app-credentials), having some sort of a stepper component might provide a better UX than scrolling through a potentially really long page.

[slorber]

having some sort of a stepper component

This is a bit vague to me. Which stepper UX do you want to have exactly?

Can you show any production example similar to your desired outcome? (ie including one large screenshot + text per step)

What prevents you from building this right now as a custom React component?

---

I'm not against such component but it's opinionated and I never saw it on any Docusaurus site so far

So if we build it for the need of user1, and then later user2 come up with another stepper need with different UX/UI opinions, it's bad.

What I would do:

• we wait for 3 userland implementations of a stepper component used on actual production Docusaurus sites, and if they present similarities we can start working on designing an API that works for those 3 user-cases
• if nobody build this in userland, or UX/UI is too different to find a good abstraction, it stays in userland

[Josh-Cena]

I never saw it on any Docusaurus site so far

It's, well, chicken and egg. Users don't bother making it because using a numbered list or several paragraphs work just as fine. But if we can make one, surely we'll see adoption. I frankly think it's a very nice doc practice, similar to tabs or details, that enables rich navigation/organization.

it's opinionated

Docusaurus is opinionated; even more opinionated is Infima, which is all about providing useful OOTB layouts for common components. Given that MUI and Zendesk both have such a component with similar UI/UX, I don't think it would be too hard to make.

Docusaurus is ultimately content-driven. Most users are only expecting something that "works", and the more convenient it is, the better. Not everyone is Supabase making their branded sites with Docusaurus.

[petrbroz]

This is a bit vague to me. Which stepper UX do you want to have exactly?

I don't have any specific requirement for the UX. Just a single area where the user can jump through multiple steps of a specific process, with the steps themselves being visualized either horizontally (example 1, example 2), or vertically (example 1, example 2).

What prevents you from building this right now as a custom React component?

Other than not being as experienced with React development, probably nothing. I will most likely try and implement something like this myself but wanted to introduce the idea on Canny to see if others would be interested in this type of component as well.

[slorber]

I frankly think it's a very nice doc practice, similar to tabs or details, that enables rich navigation/organization.

Do we have great examples of documentation with a stepper component?

Do they solve @petrbroz use-case?

Given that MUI and Zendesk both have such a component

Those UI libs are generally quite bloated

I don't think it would be too hard to make.

It's not a matter of difficulty to implement but rather to decide if it should be part of Docusaurus API surface.

I understand that if it's provided then users will use it, and we try to make it convenient.

But is this a pattern we want to encourage?

Is this a good documentation practice?

I really don't know, I'd like to see some research being done before implementing this.

If we can't find it on any Docusaurus site, maybe other docs sites have steppers?

---

Also, have some technical concerns regarding the ability to support accessibility and progressive enhancement for this UX

[Josh-Cena]

A11y is likely not a problem, but progressive enhancement could be 🤔

[lex111]

Apparently this is too specific component, in Infima implemented components that are more or less often will be used in the reality. I can't even find a use for this component in the built-in components of Docusaurus. So personally I wanted to keep Infima as minimalist and small in size as possible as it is now. Actually I had the idea of making two versions of Infima: a kind of "lite" and "extended". But in any case, it requires a lot of effort to refactor the current code base.