SetupWizard

Code

import { SetupWizard } from "@fadymondy/nasaq/web";export function Setup({ done, canFinish }: { done: string[]; canFinish: boolean }) {  return (    <SetupWizard      title="Set up your workspace"      completed={done}      canFinish={canFinish}      gateMessage={canFinish ? undefined : "Connect an agent first."}      steps={[        { id: "name", title: "Name", content: <input aria-label="Name" /> },        { id: "agent", title: "Agent", content: <p>Run the command.</p> },      ]}      onStepComplete={async (id) => api.saveStep(id)}      onFinish={async () => api.finish()}    />  );}declare const api: { saveStep(id: string): Promise<void>; finish(): Promise<void> };

Onboarding · beta

Live examples and controls: SetupWizard in the lab.

InstallCopy Anchor Link

npx shadcn@latest add https://docs.nasaqui.com/r/setup-wizard.json

Owns the order, gating and completion of a first-run flow. Each step body is your own form. The server decides when setup may finish: pass canFinish and completed from it. AgentEnrollWait is a ready-made step body for connecting an agent: it shows the command, then waits live until the agent checks in.

When to useCopy Anchor Link

• First-run setup of a workspace, project or integration.
• Guided connection of a machine or agent.

When not to useCopy Anchor Link

• A single form: use a form.
• Ongoing settings: use a settings page.

ImportCopy Anchor Link

import { AgentEnrollWait, SetupWizard } from "@fadymondy/nasaq/web";
// inside this monorepo: "@nasaq/web"

Quick startCopy Anchor Link

import { SetupWizard } from "@fadymondy/nasaq/web";

export function Setup({ done, canFinish }: { done: string[]; canFinish: boolean }) {
  return (
    <SetupWizard
      title="Set up your workspace"
      completed={done}
      canFinish={canFinish}
      gateMessage={canFinish ? undefined : "Connect an agent first."}
      steps={[
        { id: "name", title: "Name", content: <input aria-label="Name" /> },
        { id: "agent", title: "Agent", content: <p>Run the command.</p> },
      ]}
      onStepComplete={async (id) => api.saveStep(id)}
      onFinish={async () => api.finish()}
    />
  );
}

declare const api: { saveStep(id: string): Promise<void>; finish(): Promise<void> };

AnatomyCopy Anchor Link

SetupWizard                   data-slot="setup-wizard"
├─ header (title, description)
├─ Stepper rail (md+) | Progress bar (mobile)
├─ current step: title, description, Optional badge, content
├─ error / gate message      role="alert"
├─ Back · Skip · Continue | Finish
└─ done screen               title, description, doneAction

APICopy Anchor Link

SetupWizard: div props (except children, title) plus:

AgentEnrollWait: command, status (waiting, connected, timeout, failed), agent ({ name, host, version, system }), elapsed, error, onRetry, hint, labels. Poll on the host and feed it.

ExamplesCopy Anchor Link

A step that holds Continue until the agent connects

import { AgentEnrollWait, type SetupStep } from "@fadymondy/nasaq/web";

export const step = (status: "waiting" | "connected"): SetupStep => ({
  id: "agent",
  title: "Connect an agent",
  ready: status === "connected",
  content: <AgentEnrollWait command="curl -fsSL https://get.example.com | sh" status={status} />,
});

AccessibilityCopy Anchor Link

• The rail is a list with aria-current="step". Moving forward or back focuses the new step heading.
• Status changes in AgentEnrollWait are announced politely; errors use role="alert".
• Buttons show a spinner and aria-busy while a step saves.

RTL & i18nCopy Anchor Link

• English and Arabic are built in; pass labels to override.
• Back and Continue arrows mirror; the command is always left to right and copyable.

Styling & tokensCopy Anchor Link

• Built from Stepper, Progress, Button, Alert, CopyField and Spinner; tokens only.

Do / Don'tCopy Anchor Link

• Do let the server, not the client, decide when setup is complete.
• Do mark truly optional steps optional.
• Don't hide why Finish is blocked: set gateMessage.
• Don't poll faster than every couple of seconds.

RelatedCopy Anchor Link

• stepper
• progress
• copy-field

LabCopy Anchor Link

https://docs.nasaqui.com/?path=/docs/components-onboarding-pages-setup-wizard--docs