Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

7.3 KB
Raw Blame
import { IconCheckCircle, IconWarning } from '@posthog/icons'
import { Tooltip } from '@posthog/lemon-ui'

import { cn } from 'lib/utils/css-classes'

export interface GuidedWizardStep<Step extends string = string> {
    step: Step
    label: string
    optional?: boolean
    /** Rendered as data-attr on the step button, for autocapture analytics. */
    dataAttr?: string
}

export interface GuidedWizardStepperProps<Step extends string> {
    steps: GuidedWizardStep<Step>[]
    currentStep: Step
    /**
     * Where a currentStep that isn't in steps sorts: 'start' leaves every step upcoming (e.g. a
     * template picker shown before the wizard), 'end' marks every step completed (e.g. a success
     * screen shown after it). Defaults to 'start'.
     */
    unlistedStepPosition?: 'start' | 'end'
    onStepClick?: (step: Step) => void
    stepErrors?: Partial<Record<Step, string[]>>
    /** Steps that stay in the sequence for consistent numbering but can't be navigated to, keyed to the reason why. */
    disabledSteps?: Partial<Record<Step, string>>
    className?: string
    'aria-label'?: string
}

export function GuidedWizardStepper<Step extends string>({
    steps,
    currentStep,
    unlistedStepPosition = 'start',
    onStepClick,
    stepErrors = {},
    disabledSteps = {},
    className,
    'aria-label': ariaLabel = 'Wizard progress',
}: GuidedWizardStepperProps<Step>): JSX.Element {
    const currentStepIndex = steps.findIndex(({ step }) => step === currentStep)
    const currentOrder = currentStepIndex >= 0 ? currentStepIndex : unlistedStepPosition === 'end' ? steps.length : -1
    const currentStepHasErrors = (stepErrors[currentStep]?.length ?? 0) > 0
    const isInteractive = !!onStepClick

    const handleStepClick = (step: Step, targetOrder: number): void => {
        // Block navigation if current step has errors (except going back)
        if (currentStepHasErrors && targetOrder > currentOrder) {
            return // Don't navigate forward when current step has errors
        }
        onStepClick?.(step)
    }

    return (
        <nav className={cn('flex items-center', className)} aria-label={ariaLabel}>
            {steps.map((step, index) => {
                const isCompleted = currentOrder > index
                const isCurrent = currentStep === step.step
                const hasErrors = (stepErrors[step.step]?.length ?? 0) > 0
                const isBlocked = isInteractive && currentStepHasErrors && index > currentOrder
                const disabledReason = disabledSteps[step.step]

                const button = (
                    <button
                        type="button"
                        onClick={() => !disabledReason && handleStepClick(step.step, index)}
                        // aria-disabled instead of disabled so the button keeps pointer events (the tooltips need hover) and its tab-order slot
                        aria-disabled={isBlocked || !!disabledReason || !isInteractive}
                        data-attr={step.dataAttr}
                        className={cn(
                            'group flex items-center gap-1.5 px-2 py-1 rounded',
                            'transition-all duration-150',
                            'focus:outline-none focus-visible:ring-1 focus-visible:ring-accent',
                            isBlocked && 'opacity-50 cursor-not-allowed',
                            !isBlocked && disabledReason && 'opacity-50 cursor-default',
                            !isBlocked &&
                                !disabledReason &&
                                isInteractive &&
                                'hover:bg-fill-button-tertiary-hover active:scale-[0.98]',
                            !isInteractive && 'cursor-default'
                        )}
                        aria-current={isCurrent ? 'step' : undefined}
                    >
                        {/* Indicator: errors outrank the completed checkmark, current or not */}
                        {hasErrors ? (
                            <Tooltip
                                title={stepErrors[step.step]?.map((error) => (
                                    <div key={error}>{error}</div>
                                ))}
                            >
                                <IconWarning className="size-5 shrink-0 text-warning" />
                            </Tooltip>
                        ) : isCompleted ? (
                            <IconCheckCircle className="size-5 shrink-0 text-success" />
                        ) : (
                            <span
                                className={cn(
                                    'flex items-center justify-center size-5 shrink-0 rounded-full text-xs font-semibold',
                                    'transition-all duration-150',
                                    isCurrent && 'bg-accent text-primary-inverse ring-2 ring-accent/25',
                                    !isCurrent && 'bg-surface-secondary text-secondary border border-primary'
                                )}
                            >
                                {index + 1}
                            </span>
                        )}

                        {/* Reserve the bold label width so changing steps cannot move neighboring buttons. */}
                        <span
                            className="grid text-sm after:invisible after:font-semibold after:content-[attr(data-label)] after:[grid-area:1/1]"
                            data-label={step.label}
                        >
                            <span
                                className={cn(
                                    '[grid-area:1/1] transition-colors duration-150',
                                    isCurrent && 'font-semibold text-primary',
                                    isCompleted && 'font-medium text-primary',
                                    !isCompleted && !isCurrent && 'text-secondary'
                                )}
                            >
                                {step.label}
                            </span>
                        </span>

                        {step.optional && <span className="text-xs text-tertiary">optional</span>}
                    </button>
                )

                return (
                    <div key={step.step} className="flex items-center">
                        {/* Connector */}
                        {index > 0 && (
                            <div
                                className={cn(
                                    'w-6 h-px transition-colors duration-150',
                                    hasErrors
                                        ? 'bg-warning'
                                        : isCompleted || isCurrent
                                          ? 'bg-success'
                                          : 'bg-border-primary'
                                )}
                            />
                        )}

                        {/* Step */}
                        {isBlocked ? (
                            <Tooltip title="Fix errors before proceeding">{button}</Tooltip>
                        ) : disabledReason ? (
                            <Tooltip title={disabledReason}>{button}</Tooltip>
                        ) : (
                            button
                        )}
                    </div>
                )
            })}
        </nav>
    )
}