{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "onboarding-wizard",
  "title": "Onboarding Wizard",
  "description": "Resumable setup steps with validation, progress, optional steps, and completion.",
  "dependencies": [
    "class-variance-authority"
  ],
  "registryDependencies": [
    "button",
    "https://uaiblocks.dev/r/uai-theme.json",
    "https://uaiblocks.dev/r/step-indicator.json",
    "https://uaiblocks.dev/r/status-banner.json",
    "https://uaiblocks.dev/r/uai-utils.json"
  ],
  "files": [
    {
      "path": "src/registry/uai/blocks/onboarding-wizard.tsx",
      "content": "\"use client\";\n\nimport { cva } from \"class-variance-authority\";\nimport {\n  type ComponentProps,\n  createContext,\n  type ReactNode,\n  useContext,\n  useEffect,\n  useId,\n  useLayoutEffect,\n  useRef,\n  useState,\n} from \"react\";\nimport { Button } from \"@/components/ui/button\";\nimport {\n  StatusBanner,\n  StatusBannerContent,\n  StatusBannerDescription,\n  StatusBannerIcon,\n} from \"@/components/ui/uai/status-banner\";\nimport {\n  StepIndicator,\n  StepIndicatorStep,\n  type StepIndicatorVariant,\n} from \"@/components/ui/uai/step-indicator\";\nimport { cn } from \"@/lib/uai-utils\";\n\nexport const ONBOARDING_WIZARD_VARIANTS = [\"sidebar\", \"stacked\", \"compact\"] as const;\nexport type OnboardingWizardVariant = (typeof ONBOARDING_WIZARD_VARIANTS)[number];\n/** Return an error message to block the step, or nothing to continue. */\nexport type OnboardingWizardValidate = () =>\n  | string\n  | null\n  | undefined\n  | Promise<string | null | undefined>;\n\nexport type OnboardingWizardProps = Omit<ComponentProps<\"section\">, \"defaultValue\"> & {\n  variant?: OnboardingWizardVariant;\n  /** The current step. Persist it to resume setup later. */\n  value?: string;\n  defaultValue?: string;\n  onValueChange?: (value: string) => void;\n  /** Runs after the last step validates. Throw or reject with an Error to show its message. */\n  onComplete?: () => Promise<unknown> | unknown;\n};\n\ntype Step = { value: string; optional: boolean; validate?: OnboardingWizardValidate };\ntype WizardContext = {\n  id: string;\n  variant: OnboardingWizardVariant;\n  steps: Step[];\n  current: string;\n  index: number;\n  reached: number;\n  error: string | null;\n  pending: boolean;\n  complete: boolean;\n  register: (step: Step) => () => void;\n  goTo: (value: string) => void;\n  next: (options?: { skip?: boolean }) => Promise<void>;\n  back: () => void;\n};\nconst Context = createContext<WizardContext | null>(null);\nfunction useWizard(part: string) {\n  const context = useContext(Context);\n  if (!context) throw new Error(`${part} must be used within OnboardingWizard`);\n  return context;\n}\nconst PanelContext = createContext<string | null>(null);\n\nconst onboardingWizardVariants = cva(\n  \"box-border @container min-w-0 border bg-card text-[13px]/[18px] text-card-foreground\",\n  {\n    variants: {\n      variant: {\n        sidebar: \"rounded-[14px] p-[clamp(16px,4cqi,28px)]\",\n        stacked: \"mx-auto max-w-180 rounded-[14px] p-[clamp(16px,4cqi,28px)]\",\n        compact: \"mx-auto max-w-130 rounded-xl p-4\",\n      },\n    },\n  },\n);\n\nconst onboardingWizardButtonVariants = cva(\n  \"cursor-pointer rounded-full border-0 py-0 [transition:background-color_120ms_ease-out,color_120ms_ease-out,filter_120ms_ease-out,scale_140ms_cubic-bezier(0.23,1,0.32,1)] focus-visible:ring-0 focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-2 focus-visible:outline-ring enabled:active:scale-[0.97] disabled:cursor-not-allowed disabled:opacity-60 motion-reduce:transition-none motion-reduce:enabled:active:scale-100\",\n  {\n    variants: {\n      emphasis: {\n        primary: \"bg-primary text-primary-foreground hover:bg-primary enabled:hover:brightness-108\",\n        secondary:\n          \"bg-secondary text-secondary-foreground enabled:hover:bg-[color-mix(in_oklab,var(--secondary)_85%,var(--foreground))]\",\n        ghost:\n          \"bg-transparent text-muted-foreground enabled:hover:bg-accent enabled:hover:text-accent-foreground\",\n      },\n      size: {\n        default: \"h-8 px-3.5 text-[13px] has-[>svg]:px-3.5\",\n        compact: \"h-7 px-3 text-[12.5px] has-[>svg]:px-3\",\n      },\n    },\n  },\n);\n\nconst enterMotion =\n  \"animate-[enter_240ms_var(--ease-out-quint)_both] fade-in-0 slide-in-from-bottom-1 motion-reduce:animate-none\";\n\nconst indicatorVariants: Record<OnboardingWizardVariant, StepIndicatorVariant> = {\n  sidebar: \"vertical\",\n  stacked: \"horizontal\",\n  compact: \"compact\",\n};\n\n/**\n * Guides setup through ordered panels. Steps register in document order; the current step is\n * controllable so applications can persist and resume progress.\n */\nexport function OnboardingWizard({\n  variant = \"sidebar\",\n  value,\n  defaultValue,\n  onValueChange,\n  onComplete,\n  children,\n  className,\n  ...props\n}: OnboardingWizardProps) {\n  const id = useId();\n  const [steps, setSteps] = useState<Step[]>([]);\n  const [internal, setInternal] = useState(defaultValue);\n  const [error, setError] = useState<string | null>(null);\n  const [pending, setPending] = useState(false);\n  const [complete, setComplete] = useState(false);\n  const current = value ?? internal ?? steps[0]?.value ?? \"\";\n  const index = Math.max(\n    0,\n    steps.findIndex((step) => step.value === current),\n  );\n  const [reached, setReached] = useState(index);\n  const furthest = Math.max(reached, index);\n  useEffect(() => {\n    setReached((value) => Math.max(value, index));\n  }, [index]);\n\n  const goTo = (next: string) => {\n    setError(null);\n    if (value === undefined) setInternal(next);\n    onValueChange?.(next);\n  };\n  const next = async ({ skip = false } = {}) => {\n    const step = steps[index];\n    if (!step || pending) return;\n    const panel = document.getElementById(`${id}-panel-${step.value}`);\n    if (!skip) {\n      const fields = panel?.querySelectorAll<HTMLInputElement>(\"input, select, textarea\") ?? [];\n      const invalid = Array.from(fields).find((field) => !field.validity.valid);\n      if (invalid) {\n        setError(invalid.validationMessage || \"Check the highlighted field.\");\n        invalid.focus();\n        return;\n      }\n      setPending(true);\n      try {\n        const message = await step.validate?.();\n        if (message) {\n          setError(message);\n          return;\n        }\n      } finally {\n        setPending(false);\n      }\n    }\n    const following = steps[index + 1];\n    if (following) {\n      goTo(following.value);\n      return;\n    }\n    setPending(true);\n    try {\n      await onComplete?.();\n      setError(null);\n      setComplete(true);\n    } catch (reason) {\n      setError(reason instanceof Error ? reason.message : \"Setup could not be finished.\");\n    } finally {\n      setPending(false);\n    }\n  };\n\n  return (\n    <Context.Provider\n      value={{\n        id,\n        variant,\n        steps,\n        current,\n        index,\n        reached: furthest,\n        error,\n        pending,\n        complete,\n        register: (step) => {\n          setSteps((list) =>\n            list.some((item) => item.value === step.value)\n              ? list.map((item) => (item.value === step.value ? step : item))\n              : [...list, step],\n          );\n          return () => setSteps((list) => list.filter((item) => item.value !== step.value));\n        },\n        goTo,\n        next,\n        back: () => {\n          const previous = steps[index - 1];\n          if (previous) goTo(previous.value);\n        },\n      }}\n    >\n      <section\n        aria-labelledby={`${id}-title`}\n        data-slot=\"onboarding-wizard\"\n        data-variant={variant}\n        className={cn(onboardingWizardVariants({ variant }), className)}\n        {...props}\n      >\n        <div\n          className={cn(\n            \"grid min-w-0 gap-5 [grid-template-areas:'header'_'progress'_'body']\",\n            variant === \"sidebar\" &&\n              \"@min-[720px]:grid-cols-[220px_minmax(0,1fr)] @min-[720px]:grid-rows-[auto_1fr] @min-[720px]:gap-x-8 @min-[720px]:[grid-template-areas:'progress_header'_'progress_body']\",\n          )}\n        >\n          {children}\n        </div>\n      </section>\n    </Context.Provider>\n  );\n}\n\nexport function OnboardingWizardHeader({ className, ...props }: ComponentProps<\"header\">) {\n  return (\n    <header\n      data-slot=\"onboarding-wizard-header\"\n      className={cn(\"grid min-w-0 gap-1 [grid-area:header]\", className)}\n      {...props}\n    />\n  );\n}\n\nexport function OnboardingWizardTitle({ className, ...props }: ComponentProps<\"h2\">) {\n  const { id, variant } = useWizard(\"OnboardingWizardTitle\");\n  return (\n    <h2\n      data-slot=\"onboarding-wizard-title\"\n      className={cn(\n        \"m-0 font-semibold tracking-[-0.01em]\",\n        variant === \"compact\" ? \"text-[15px]/5\" : \"text-lg/6\",\n        className,\n      )}\n      {...props}\n      id={`${id}-title`}\n    />\n  );\n}\n\nexport function OnboardingWizardDescription({ className, ...props }: ComponentProps<\"p\">) {\n  return (\n    <p\n      data-slot=\"onboarding-wizard-description\"\n      className={cn(\"m-0 text-pretty text-muted-foreground\", className)}\n      {...props}\n    />\n  );\n}\n\n/** \"Step 2 of 4\", announced politely as the step changes. */\nexport function OnboardingWizardStepCount({ className, ...props }: ComponentProps<\"p\">) {\n  const { index, steps } = useWizard(\"OnboardingWizardStepCount\");\n  return (\n    <p\n      aria-live=\"polite\"\n      data-slot=\"onboarding-wizard-step-count\"\n      className={cn(\"m-0 text-[12px] text-subtle-foreground tabular-nums\", className)}\n      {...props}\n    >\n      Step {Math.min(index + 1, steps.length || 1)} of {steps.length || 1}\n    </p>\n  );\n}\n\nexport function OnboardingWizardProgress({\n  className,\n  ...props\n}: Omit<ComponentProps<typeof StepIndicator>, \"variant\">) {\n  const { variant } = useWizard(\"OnboardingWizardProgress\");\n  return (\n    <StepIndicator\n      aria-label=\"Setup progress\"\n      className={cn(\"min-w-0 self-start [grid-area:progress]\", className)}\n      {...props}\n      variant={indicatorVariants[variant]}\n    />\n  );\n}\n\n/** A step in the progress list. Reached steps become buttons that return to that step. */\nexport function OnboardingWizardProgressStep({\n  value,\n  children,\n  ...props\n}: Omit<ComponentProps<typeof StepIndicatorStep>, \"status\" | \"optional\"> & { value: string }) {\n  const context = useWizard(\"OnboardingWizardProgressStep\");\n  const position = context.steps.findIndex((step) => step.value === value);\n  const step = context.steps[position];\n  const isCurrent = value === context.current && !context.complete;\n  const status = isCurrent\n    ? \"current\"\n    : context.complete || (position >= 0 && position < context.reached)\n      ? \"complete\"\n      : \"upcoming\";\n  const reachable = position >= 0 && position <= context.reached && !isCurrent && !context.complete;\n  return (\n    <StepIndicatorStep {...props} status={status} optional={step?.optional ?? false}>\n      {reachable ? (\n        <button\n          type=\"button\"\n          onClick={() => context.goTo(value)}\n          className=\"grid cursor-pointer gap-0.5 border-0 bg-transparent p-0 text-start text-inherit hover:text-foreground focus-visible:rounded-[6px] focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-2 focus-visible:outline-ring\"\n        >\n          {children}\n        </button>\n      ) : (\n        <span className=\"grid gap-0.5\">{children}</span>\n      )}\n    </StepIndicatorStep>\n  );\n}\n\n/** Holds the panels, error, and footer. */\nexport function OnboardingWizardBody({ className, ...props }: ComponentProps<\"div\">) {\n  return (\n    <div\n      data-slot=\"onboarding-wizard-body\"\n      className={cn(\"grid min-w-0 content-start gap-4 [grid-area:body]\", className)}\n      {...props}\n    />\n  );\n}\n\nexport type OnboardingWizardPanelProps = ComponentProps<\"fieldset\"> & {\n  value: string;\n  optional?: boolean;\n  /** Runs before advancing, after native field validation passes. */\n  validate?: OnboardingWizardValidate;\n};\n\n/** One step. Inactive panels stay mounted and hidden so entered values survive navigation. */\nexport function OnboardingWizardPanel({\n  value,\n  optional = false,\n  validate,\n  className,\n  ...props\n}: OnboardingWizardPanelProps) {\n  const context = useWizard(\"OnboardingWizardPanel\");\n  const validateRef = useRef(validate);\n  validateRef.current = validate;\n  const { register } = context;\n  const registerRef = useRef(register);\n  registerRef.current = register;\n  useLayoutEffect(\n    () =>\n      registerRef.current({\n        value,\n        optional,\n        validate: () => validateRef.current?.(),\n      }),\n    [value, optional],\n  );\n  const active = context.current === value && !context.complete;\n  return (\n    <PanelContext.Provider value={value}>\n      <fieldset\n        data-slot=\"onboarding-wizard-panel\"\n        className={cn(\"m-0 grid min-w-0 gap-3.5 border-0 p-0\", enterMotion, className)}\n        {...props}\n        id={`${context.id}-panel-${value}`}\n        aria-labelledby={`${context.id}-panel-${value}-title`}\n        hidden={!active}\n        disabled={context.pending}\n        data-value={value}\n      />\n    </PanelContext.Provider>\n  );\n}\n\n/** The step heading. Focus moves here when the step changes after the first render. */\nexport function OnboardingWizardPanelTitle({ className, ...props }: ComponentProps<\"h3\">) {\n  const context = useWizard(\"OnboardingWizardPanelTitle\");\n  const value = useContext(PanelContext);\n  if (value === null) {\n    throw new Error(\"OnboardingWizardPanelTitle must be used within OnboardingWizardPanel\");\n  }\n  const ref = useRef<HTMLHeadingElement>(null);\n  const mounted = useRef(false);\n  const active = context.current === value;\n  useEffect(() => {\n    if (active && mounted.current) ref.current?.focus();\n    mounted.current = true;\n  }, [active]);\n  return (\n    <h3\n      tabIndex={-1}\n      data-slot=\"onboarding-wizard-panel-title\"\n      className={cn(\"m-0 text-[15px]/5 font-medium outline-none\", className)}\n      {...props}\n      ref={ref}\n      id={`${context.id}-panel-${value}-title`}\n    />\n  );\n}\n\nexport function OnboardingWizardPanelDescription({ className, ...props }: ComponentProps<\"p\">) {\n  return (\n    <p\n      data-slot=\"onboarding-wizard-panel-description\"\n      className={cn(\"m-0 -mt-2 text-pretty text-muted-foreground\", className)}\n      {...props}\n    />\n  );\n}\n\n/** Shows the current validation or completion error as an error Status Banner. */\nexport function OnboardingWizardError({\n  children,\n  ...props\n}: Omit<ComponentProps<typeof StatusBanner>, \"tone\">) {\n  const context = useWizard(\"OnboardingWizardError\");\n  if (!context.error) return null;\n  return (\n    <StatusBanner variant=\"tinted\" {...props} tone=\"error\">\n      <StatusBannerIcon />\n      <StatusBannerContent>\n        {children}\n        <StatusBannerDescription className=\"text-inherit\">{context.error}</StatusBannerDescription>\n      </StatusBannerContent>\n    </StatusBanner>\n  );\n}\n\nexport function OnboardingWizardFooter({ className, ...props }: ComponentProps<\"div\">) {\n  const { complete } = useWizard(\"OnboardingWizardFooter\");\n  if (complete) return null;\n  return (\n    <div\n      data-slot=\"onboarding-wizard-footer\"\n      className={cn(\"flex flex-wrap items-center justify-end gap-2 pt-1\", className)}\n      {...props}\n    />\n  );\n}\n\nconst buttonSize = (variant: OnboardingWizardVariant) =>\n  variant === \"compact\" ? \"compact\" : \"default\";\n\n/** Returns to the previous step. Hidden on the first step. */\nexport function OnboardingWizardBack({ onClick, className, ...props }: ComponentProps<\"button\">) {\n  const context = useWizard(\"OnboardingWizardBack\");\n  if (context.index === 0) return null;\n  return (\n    <Button\n      type=\"button\"\n      variant=\"secondary\"\n      data-slot=\"onboarding-wizard-back\"\n      className={cn(\n        onboardingWizardButtonVariants({\n          emphasis: \"secondary\",\n          size: buttonSize(context.variant),\n        }),\n        \"mr-auto\",\n        className,\n      )}\n      {...props}\n      disabled={context.pending}\n      onClick={(event) => {\n        onClick?.(event);\n        if (!event.defaultPrevented) context.back();\n      }}\n    />\n  );\n}\n\n/** Advances without validation. Renders only on optional steps. */\nexport function OnboardingWizardSkip({ onClick, className, ...props }: ComponentProps<\"button\">) {\n  const context = useWizard(\"OnboardingWizardSkip\");\n  if (!context.steps[context.index]?.optional) return null;\n  return (\n    <Button\n      type=\"button\"\n      variant=\"ghost\"\n      data-slot=\"onboarding-wizard-skip\"\n      className={cn(\n        onboardingWizardButtonVariants({ emphasis: \"ghost\", size: buttonSize(context.variant) }),\n        className,\n      )}\n      {...props}\n      disabled={context.pending}\n      onClick={(event) => {\n        onClick?.(event);\n        if (!event.defaultPrevented) void context.next({ skip: true });\n      }}\n    />\n  );\n}\n\nfunction Advance({\n  part,\n  slot,\n  last,\n  pendingLabel,\n  children,\n  onClick,\n  className,\n  ...props\n}: ComponentProps<\"button\"> & {\n  part: string;\n  slot: string;\n  last: boolean;\n  pendingLabel: ReactNode;\n}) {\n  const context = useWizard(part);\n  if ((context.index === context.steps.length - 1) !== last) return null;\n  return (\n    <Button\n      type=\"button\"\n      data-slot={slot}\n      className={cn(\n        onboardingWizardButtonVariants({ emphasis: \"primary\", size: buttonSize(context.variant) }),\n        context.pending && \"cursor-progress\",\n        className,\n      )}\n      {...props}\n      aria-busy={context.pending || undefined}\n      onClick={(event) => {\n        onClick?.(event);\n        if (!event.defaultPrevented) void context.next();\n      }}\n    >\n      {/* Both labels share one grid cell so the button keeps its width while pending. */}\n      <span className=\"grid [&>*]:[grid-area:1/1]\">\n        <span\n          className={cn(context.pending && \"invisible\")}\n          aria-hidden={context.pending || undefined}\n        >\n          {children}\n        </span>\n        <span\n          className={cn(\n            \"animate-shimmer bg-[linear-gradient(90deg,color-mix(in_oklab,currentColor_55%,transparent)_0%,color-mix(in_oklab,currentColor_55%,transparent)_35%,currentColor_50%,color-mix(in_oklab,currentColor_55%,transparent)_65%,color-mix(in_oklab,currentColor_55%,transparent)_100%)] bg-[length:200%_100%] bg-clip-text [-webkit-text-fill-color:transparent] motion-reduce:animate-none motion-reduce:bg-none motion-reduce:[-webkit-text-fill-color:currentColor]\",\n            !context.pending && \"invisible animate-none\",\n          )}\n          aria-hidden={!context.pending || undefined}\n        >\n          {pendingLabel}\n        </span>\n      </span>\n    </Button>\n  );\n}\n\n/** Validates the current step and moves on. Hidden on the last step. */\nexport function OnboardingWizardNext({\n  pendingLabel = \"Checking…\",\n  ...props\n}: ComponentProps<\"button\"> & { pendingLabel?: ReactNode }) {\n  return (\n    <Advance\n      {...props}\n      part=\"OnboardingWizardNext\"\n      slot=\"onboarding-wizard-next\"\n      last={false}\n      pendingLabel={pendingLabel}\n    />\n  );\n}\n\n/** Validates the last step and calls `onComplete`. Renders only on the last step. */\nexport function OnboardingWizardFinish({\n  pendingLabel = \"Finishing…\",\n  ...props\n}: ComponentProps<\"button\"> & { pendingLabel?: ReactNode }) {\n  return (\n    <Advance\n      {...props}\n      part=\"OnboardingWizardFinish\"\n      slot=\"onboarding-wizard-finish\"\n      last\n      pendingLabel={pendingLabel}\n    />\n  );\n}\n\n/** Replaces the panels once setup finishes. Focus moves here so the result is announced. */\nexport function OnboardingWizardComplete({ className, ...props }: ComponentProps<\"div\">) {\n  const context = useWizard(\"OnboardingWizardComplete\");\n  const ref = useRef<HTMLDivElement>(null);\n  useEffect(() => {\n    if (context.complete) ref.current?.focus();\n  }, [context.complete]);\n  if (!context.complete) return null;\n  return (\n    <div\n      role=\"status\"\n      tabIndex={-1}\n      data-slot=\"onboarding-wizard-complete\"\n      className={cn(\n        \"grid min-w-0 gap-2 bg-[color-mix(in_oklab,var(--success)_8%,var(--card))] p-5 shadow-[inset_0_0_0_1px_color-mix(in_oklab,var(--success)_24%,transparent)] outline-offset-2\",\n        context.variant === \"compact\" ? \"rounded-xl\" : \"rounded-[14px]\",\n        enterMotion,\n        className,\n      )}\n      {...props}\n      ref={ref}\n    />\n  );\n}\n",
      "type": "registry:component",
      "target": "@components/uai/onboarding-wizard.tsx"
    }
  ],
  "categories": [
    "authentication",
    "onboarding",
    "forms"
  ],
  "type": "registry:block"
}