/**
 * Help System Types
 *
 * Types for help tours, prompts, and guides
 */

/**
 * Help action button configuration
 *
 * Defines an action button that appears in a help prompt
 */
export interface HelpActionProps {
  /** Display label for the button */
  action_label: string;

  /** Type of action (e.g., 'navigate', 'dismiss', 'external_link') */
  action_type: string;

  /** Optional external URL for link actions */
  action_url?: string;

  /** Navigation options for internal app navigation */
  internal_nav_options: {
    /** Navigation stack name */
    page_stack: string;
    /** Page/screen name to navigate to */
    page: string;
    /** Parameters to pass to the page */
    page_params: any;
  };

  /** Button background color */
  button_color: string;

  /** Button border color */
  button_border_color: string;

  /** Font/text style for button label */
  action_label_font: string;
}

/**
 * Help media object
 *
 * Defines media (image/video) displayed in a help prompt
 */
export interface HelpMediaObjProps {
  /** URL to the media file */
  media_url: string;

  /** Height in CSS units (px, %, etc.) */
  height: string;

  /** Width in CSS units (px, %, etc.) */
  width: string;
}

/**
 * Help tour configuration
 *
 * Defines a multi-step guided tour through app features
 */
export interface HelpTourProps {
  /** Unique help tour ID */
  help_tour_id: string;

  /** Display name for the tour */
  help_tour_name: string;

  /** Description of what the tour covers */
  help_tour_description: string;

  /** Whether the tour is active and available */
  status: 'active' | 'inactive';

  /** Seconds between automatic carousel transitions */
  carousel_change_seconds: number;

  /** Timestamp when tour was created */
  create_datetime: any;

  /** Timestamp of last update */
  last_update_datetime: any;
}

/**
 * Help prompt
 *
 * Individual help message or tooltip that can be shown to users
 */
export interface HelpPromptProps {
  /** Unique help prompt ID */
  help_prompt_id: string;

  /** Native UI element ID this prompt is attached to */
  client_native_id: string;

  /** Optional tour ID if this prompt is part of a tour */
  help_tour_id?: string;

  /** Order/priority within a tour */
  tour_priority?: number;

  /** Prompt title text */
  title: string;

  /** Optional custom color for title */
  title_font_color?: string;

  /** Main body text of the prompt */
  body: string;

  /** Optional custom color for body text */
  body_font_color?: string;

  /** Type of media to display */
  media_type?: 'IMAGE' | 'VIDEO';

  /** Optional media object (image or video) */
  media_obj?: HelpMediaObjProps;

  /** Optional footer text */
  footer?: string;

  /** Optional custom color for footer text */
  footer_font_color?: string;

  /** Background color for the help overlay */
  help_background_color?: string;

  /** Background overlay opacity color (RGBA) */
  help_background_opacity_color: string;

  /** Array of action buttons */
  actions: HelpActionProps[];

  /** Whether this prompt is active */
  status: 'active' | 'inactive';

  /** Timestamp when created */
  create_datetime: any;

  /** Timestamp of last update */
  last_update_datetime: any;

  /** Type of prompt (tooltip, modal, tour_step, etc.) */
  prompt_type: string;
}

/**
 * Guide response
 *
 * Response containing help content to display to the user
 */
export interface GuideResponseProps {
  /** Type of help content being shown */
  view_type: 'prompt' | 'tour';

  /** Single prompt if view_type is 'prompt' */
  help_prompt?: HelpPromptProps;

  /** Tour configuration if view_type is 'tour' */
  help_tour?: HelpTourProps;

  /** Array of prompts in the tour */
  tour_prompts?: HelpPromptProps[];

  /** ID of the currently active prompt in the tour */
  active_tour_prompt?: string;
}

/**
 * Guide wrapper props
 *
 * Props for the guide/tour wrapper component
 */
export interface GuideWrapProps {
  /** Array of tour step prompts */
  tour?: HelpPromptProps[];

  /** Tour configuration */
  help_tour?: HelpTourProps;

  /** Callback when tour is completed or cancelled */
  onComplete?: (state: 'cancelled' | 'complete') => void;

  /** Whether the guide is currently active/visible */
  active?: boolean;
}

/**
 * Tour step definition
 *
 * Defines a single step in a product tour
 */
export interface TourStepProps {
  /** Native UI element ID to highlight */
  nativeID: string;

  /** Optional step title */
  title?: string;

  /** Optional step body text */
  body?: string;

  /** Whether the highlighted element is clickable during the tour */
  clickable?: boolean;

  /** Position of the tooltip relative to the element */
  position?: 'top' | 'bottom' | 'left' | 'right';

  /** Optional image URL to display */
  image?: string;

  /** Step priority/order in the tour */
  priority?: number;
}

/**
 * Create group step
 *
 * Step in a guided group creation flow
 */
export interface CreateGroupStepProps {
  /** Step number */
  num: number;

  /** Step title */
  title: string;

  /** Unique key for this step */
  step_key: string;

  /** Description text for the step */
  description: string;
}

/**
 * Microsoft Clarity analytics integration
 *
 * TypeScript definitions for Clarity analytics SDK
 */
export interface ClarityProps {
  /** Give consent for Clarity tracking */
  consent: () => void;

  /** Identify a user session */
  identify: (
    customId: string,
    customSessionId?: string,
    customPageId?: string,
    friendlyName?: string
  ) => Promise<{
    /** Clarity user ID */
    id: string;
    /** Clarity session ID */
    session: string;
    /** Clarity page ID */
    page: string;
    /** Optional user hint */
    userHint?: string;
  }>;

  /** Set a custom variable for the session */
  set: (key: string, value: string | string[]) => void;

  /** Track a custom event */
  event: (name: string) => void;
}