import { TNode, Value } from '@tempots/dom';
/**
 * Placement of the tour tooltip relative to the target element.
 */
export type TourTooltipPlacement = 'top' | 'bottom' | 'left' | 'right' | 'auto';
/**
 * Behavior when the backdrop area (outside the highlighted element) is clicked.
 */
export type TourBackdropAction = 'close' | 'advance' | 'ignore';
/**
 * Definition of a single step in the onboarding tour.
 */
export interface TourStep {
    /** CSS selector or direct reference to the target element to highlight. */
    target: string | HTMLElement;
    /** Title text for the step tooltip. */
    title?: string;
    /** Description text for the step tooltip. */
    description?: string;
    /** Rich content to render inside the tooltip (replaces description if provided). */
    content?: TNode;
    /** Preferred placement of the tooltip. @default 'auto' */
    placement?: TourTooltipPlacement;
    /** Whether the user can interact with the highlighted element. @default false */
    allowInteraction?: boolean;
    /** Async validation function. Return true to allow advancing, false to block. */
    beforeNext?: () => boolean | Promise<boolean>;
}
/**
 * Configuration options for the {@link OnboardingTour} component.
 */
export interface OnboardingTourOptions {
    /** Array of tour steps to display. */
    steps: TourStep[];
    /** Behavior when backdrop is clicked. @default 'ignore' */
    backdropAction?: TourBackdropAction;
    /** Padding around the highlighted element in pixels. @default 8 @min 0 @max 32 @step 2 */
    spotlightPadding?: number;
    /** Border radius for the spotlight cutout in pixels. @default 8 @min 0 @max 24 @step 2 */
    spotlightRadius?: number;
    /** Whether to show step indicators (e.g. "Step 2 of 5"). @default true */
    showStepIndicator?: boolean;
    /** Whether to show the Skip button. @default true */
    showSkipButton?: boolean;
    /** Callback when the tour starts. @default undefined */
    onStart?: () => void;
    /** Callback when the current step changes. @default undefined */
    onStepChange?: (stepIndex: number) => void;
    /** Callback when the tour is completed (user clicks Finish on last step). @default undefined */
    onComplete?: () => void;
    /** Callback when the tour is skipped. @default undefined */
    onSkip?: () => void;
    /**
     * Where to attach the overlay in the DOM.
     * - `'body'` - Renders via a portal to the document body.
     * - `'element'` - Renders as a child of the current element context.
     * @default 'body'
     */
    container?: 'body' | 'element';
}
/**
 * Controller returned by {@link OnboardingTour} for programmatic control.
 */
export interface OnboardingTourController {
    /** Start the tour from the first step. */
    startTour: () => void;
    /** Jump to a specific step by index. */
    goToStep: (index: number) => void;
    /** End the tour immediately. */
    endTour: () => void;
    /** Whether the tour is currently active. */
    isActive: Value<boolean>;
    /** The current step index (0-based). */
    currentStep: Value<number>;
}
/**
 * A step-by-step guided tour overlay that highlights UI elements with a spotlight
 * effect and shows tooltips with navigation controls.
 *
 * Returns a tuple of `[TNode, OnboardingTourController]`.
 *
 * @param options - Configuration for steps, behavior, and callbacks
 * @returns A tuple of the tour overlay node and its controller
 *
 * @example
 * ```typescript
 * const [tour, ctrl] = OnboardingTour({
 *   steps: [
 *     { target: '#welcome-btn', title: 'Welcome', description: 'Click here to get started.' },
 *     { target: '.sidebar', title: 'Navigation', description: 'Browse sections here.' },
 *   ],
 *   onComplete: () => console.log('Tour finished!'),
 * })
 * html.div(tour)
 * ctrl.startTour()
 * ```
 */
export declare function OnboardingTour(options: OnboardingTourOptions): [TNode, OnboardingTourController];