Setup assistant

If your project doesn't have Wisty UI's theme yet, add it once with npx shadcn@latest add @wisty/cosmos. Until then, components keep shadcn's default look. Installation has the details.

SetupAssistantSummary shows how many steps are done, as words and a bar. Put it in your card's header and SetupAssistantList in its body, with SetupAssistant around the card and headingLevel={3} under the card's h2. Leave the summary out for a list inside an existing section.

A step is a task with a button or link, a setting with a switch, or a sequence of substeps. onAction and onToggleChange only ask for the work. Replace the step's progress, or the switch's checked, in steps once the work succeeds. A link never completes a step. For a sequence, completed counts finished substeps from the first: the next one is current, and later ones wait. value, defaultValue and onValueChange hold which sequences are open, apart from their progress.

• Each step's title is a heading at headingLevel, 2 by default. Set it one below the heading the list sits under.
• A sequence opens from its chevron and from its title. Both report aria-expanded and point at the substeps with aria-controls.
• Each ring is named "Step 2: Prepare your account data" and described by the step's progress label. Unknown progress shows its label on the page, and a setting that couldn't be read shows its unavailableLabel in place of the switch.
• A switch is named by its toggle's label. The On and Off beside it are hidden from screen readers, which hear the switch's state. Without onToggleChange there's no switch, and screen readers hear the label before the On or Off text.
• A link with disabled, or a later substep's link, is plain text with no href, so it takes no focus. With the button look it's a disabled button.
• If your app closes an open sequence while focus is inside it, move focus to its title first.

• The block takes its container's width. Below 32rem, a step's action and estimate move under its description.
• Titles, descriptions and substeps wrap instead of truncating. Give the card a max-w-* so lines stay readable on a wide page.

• Keep completion in steps, written by your app. Nothing in the block completes a step by itself.
• Pass an unknown progress with a label when you couldn't read it, never not-started or 0. For a setting, pass checked: null with an unavailableLabel, never false. Unknown never counts as done or not done.
• Pass partial with a message when only some steps could be read, and steps={null} when none could, never a shorter or empty list: an empty list says there are none.
• Pass loading while the steps load, never an empty list. To reload steps already shown, keep passing them with loading: the rows stay, and the summary says progress is updating instead of showing a bar that may be stale.
• Give every step a unique id, and every substep one unique within its step. Ids keep the open sequences and callbacks pointed at the right row when steps reorder.
• estimatedTime is a label. It never weighs progress, and the summary counts finished steps.
• Buttons render only with onAction, and switches only with onToggleChange. Without it, a setting shows its confirmed state as On or Off text.
• Never pass asChild or render.