Progress Steps API RFC

[nkrantz]

Progress Indicator - request for comment

We're adding a Progress Indicator (PI) to the Paste component library and we'd like your input.

Progress Indicators are sometimes called Steppers or Progress Steppers, and are used to indicate a user's progress throughout a multi-step flow. Drop feedback about the naming of this component in the thread.

Please review the following API proposal and scope decisions and let us know what you think.

Note: the designs included in this RFC are purely exploratory and we're not currently looking for design feedback. The design work for PI will happen after the scope and API are finalized and we'll request design feedback at that time.

Scope

In scope for the first release of the Progress Indicator:

• Horizontal and vertical PIs
• Incomplete, current, and completed PI steps
• Anchor steps (for PIs with URL changes on click) and button steps (for PIs with DOM updates on click) - these 2 types of PIs are visually distinct to indicate expected behavior
• Sequential (steps must be completed in order) and non sequential (steps can be completed in any order) PIs
• Disabled clickable steps (e.g. for when a step is dependent on another step)

Out of scope for the first release of the Progress Indicator:

• Status pattern for steps (e.g. warning, error)
• Responsive PI
• Numbers inside of step icons
• Fitted variant on horizontal PI for full width PIs

Components

• <ProgressIndicator> (<ol>)
  • orientation? (string) “horizontal” | “vertical” determines visual orientation of PI
  • sequential? (boolean) sequential PIs must be completed in order (can't jump forwards past incomplete steps)
  • i18nCompletedLabel (string) label to communicate that the step is completed
  • i18nCurrentLabel (string) label to communicate that the step is current
  • i18nIncompleteLabel (string) label to communicate that the step is incomplete
• <ProgressIndicatorStep> (<li>)
  • status (string) "complete" | "current" | "incomplete"
  • href? (string) for clickable steps that lead to new URLs - sets an <a> inside of the <li>
  • onClick? (function) for clickable steps that update the DOM (don't lead to new URLs) - sets a <button> inside of the <li>
  • disabled? (boolean) for clickable steps that can't currently be clicked (e.g. depends on another step)
• <ProgressIndicatorStepLabel> (<span>)
• <ProgressIndicatorStepDescription> (<span>)

API

<ProgressIndicator orientation="horizontal" sequential i18nIncompleteLabel="incomplete step" i18nCurrentLabel="current step" i18nCompleteLabel="complete step">
  <ProgressIndicatorStep status="complete" href="twilio.com/get-twilio-number">
    <ProgressIndicatorStepLabel>Get a Twilio number</ProgressIndicatorStepLabel>
    <ProgressIndicatorStepDescription>Optional description text to accompany the step label (not shown in img above)</ProgressIndicatorStepDescription>
  </ProgressIndicatorStep>
  <ProgressIndicatorStep status="complete" href="twilio.com/create-conversation>
    <ProgressIndicatorStepLabel>Create a conversation</ProgressIndicatorStepLabel>
    <ProgressIndicatorStepDescription>Optional description text to accompany the step label (not shown in img above)</ProgressIndicatorStepDescription>
  </ProgressIndicatorStep>
  <ProgressIndicatorStep status="current" href="twilio.com/add-participant>
    <ProgressIndicatorStepLabel>Add a participant</ProgressIndicatorStepLabel>
    <ProgressIndicatorStepDescription>Optional description text to accompany the step label (not shown in img above)</ProgressIndicatorStepDescription>
  </ProgressIndicatorStep>
  <ProgressIndicatorStep status="incomplete" href="twilio.com/send-receive-sms>
    <ProgressIndicatorStepLabel>Send and receive SMS</ProgressIndicatorStepLabel>
    <ProgressIndicatorStepDescription>Optional description text to accompany the step label (not shown in img above)</ProgressIndicatorStepDescription>
  </ProgressIndicatorStep>
  <ProgressIndicatorStep status="incomplete" href="twilio.com/wrapup>
    <ProgressIndicatorStepLabel>Wrap-up</ProgressIndicatorStepLabel>
    <ProgressIndicatorStepDescription>Optional description text to accompany the step label (not shown in img above)</ProgressIndicatorStepDescription>
  </ProgressIndicatorStep>
</ProgressIndicator>

Take a look at the above API in a CodeSandbox

[serifluous]

Didn't notice until now—why are numbers in steps and error status out of scope?

[serifluous]

Would/could we require either a href or onClick for each step? I'm trying to work through the design implications of this, but curious if there's an eng opinion here.

[nkrantz]

Yes that is possible!

[HartiganHM]

I like the idea of an onClick as well. Recently we had to build a custom wrapper around Anchor to work with react-router-dom@v6 and this is something we would likely have to do here as well should we ever implement this component. An onClick would at least allow us to use something like useNavigate versus solely on href.

EDIT
Realizing that might be out of scope for now, but it would be a nice to have later one 🙂

[vedant-nanda]

Would we be able to implement something like this with this new component?
Step bar with clickable buttons and have transition effects?

Screen.Recording.2023-05-18.at.9.13.18.AM.mov

[SiTaggart]

It will come with the ability to perform a click transition through the steps via url routing or client actions. We aren't including any gradients or transitions in the design.

Curious where the design came from, is your design partner involving themselves in the Design RFC?