import type { TourStepProps } from 'antd';
import type { SiteSettings } from '@/types/api';

/** Unique identifier for each tour section */
export type TourSectionId =
  | 'getting-started'
  | 'dashboard'
  | 'settings'
  | 'campaigns'
  | 'map-locations'
  | 'media-library'
  | 'user-management';

/** Context passed to step builder functions */
export interface TourStepContext {
  settings: SiteSettings;
  isMobile: boolean;
}

/** Category for grouping sections in the Tour Hub */
export type TourCategory = 'essentials' | 'features';

/** Registry entry defining a tour section */
export interface TourSection {
  id: TourSectionId;
  title: string;
  description: string;
  icon: string;
  /** Route the user must be on for this tour to run. null = layout-level (AppLayout). */
  route: string | null;
  /** Feature flag key that must be truthy. null = always available. */
  featureFlag: keyof SiteSettings | null;
  /** Sort order in the hub UI */
  order: number;
  category: TourCategory;
  /** Estimated time to complete in minutes */
  estimatedMinutes: number;
  /** Function that builds steps dynamically */
  buildSteps: (ctx: TourStepContext) => TourStepProps[];
}

/** Per-section progress as stored in Zustand */
export interface SectionProgress {
  currentStep: number;
  totalSteps: number;
  completed: boolean;
  lastActiveAt: string | null;
}

/**
 * Helper to create a target function that satisfies antd's Tour target type.
 * antd expects `(() => HTMLElement) | (() => null)` but querySelector returns
 * `HTMLElement | null`. We cast through unknown to bridge the union gap.
 */
export function domTarget(selector: string): (() => HTMLElement) | (() => null) {
  return (() => document.querySelector(selector)) as (() => HTMLElement) | (() => null);
}
