Hint System

/**
 * Create a new Hint instance
 * @param elementOrSelector - Optional target element or CSS selector for hints
 * @param options - Optional Hint configuration options
 */
new Hint(elementOrSelector?: string | HTMLElement, options?: Partial<HintOptions>): Hint;

/**
 * Create Hint instance via static method (recommended)
 * @param elementOrSelector - Optional target element or CSS selector
 */
introJs.hint(elementOrSelector?: string | HTMLElement): Hint;

import introJs from "intro.js";

// Create hint instance for entire document
const hint = introJs.hint();

// Create hint instance for specific container
const hint = introJs.hint("#main-content");

// Create hint instance with initial options
const hint = introJs.hint(document.body, {
  hintPosition: "top-middle",
  hintAnimation: true,
  hintAutoRefreshInterval: 100
});

/**
 * Render hints on the page
 */
render(): Promise<Hint>;

/**
 * Destroy and remove all hint elements from the page
 */
destroy(): Hint;

/**
 * Check if hints are currently rendered
 */
isRendered(): boolean;

/**
 * Check if the hint instance is active
 */
isActive(): boolean;

/**
 * Refresh hints on the page (updates positioning)
 */
refresh(): Hint;

import introJs from "intro.js";

const hint = introJs.hint();

// Add some hints
hint.addHint({
  element: "#help-button",
  hint: "Click for help and support",
  hintPosition: "top-middle"
});

// Render hints on the page
await hint.render();

// Check if rendered
if (hint.isRendered()) {
  console.log("Hints are visible");
}

// Clean up when done
hint.destroy();

/**
 * Add a single hint item
 * @param hint - Hint configuration object
 */
addHint(hint: HintItem): Hint;

/**
 * Set all hint items, replacing existing ones
 * @param hints - Array of hint items
 */
setHints(hints: HintItem[]): Hint;

/**
 * Get all hint items
 */
getHints(): HintItem[];

/**
 * Get a specific hint item by step ID
 * @param stepId - The hint step ID
 */
getHint(stepId: number): HintItem | undefined;

/**
 * Remove a single hint element by step ID
 * @param stepId - The hint step ID to remove
 */
removeHint(stepId: number): Hint;

import introJs from "intro.js";

const hint = introJs.hint();

// Add individual hints
hint.addHint({
  element: "#save-button",
  hint: "Save your changes",
  hintPosition: "bottom-middle"
});

hint.addHint({
  element: "#settings-icon",
  hint: "Open settings panel",
  hintPosition: "top-left",
  hintAnimation: false
});

// Add multiple hints at once
hint.setHints([
  {
    element: "#profile-menu",
    hint: "Access your profile and account settings",
    hintPosition: "bottom-right"
  },
  {
    element: "#notification-bell",
    hint: "View your latest notifications",
    hintPosition: "bottom-middle"
  }
]);

await hint.render();

/**
 * Show a specific hint on the page
 * @param stepId - The hint step ID
 */
showHint(stepId: number): Hint;

/**
 * Show all hints on the page
 */
showHints(): Promise<Hint>;

/**
 * Hide a specific hint on the page
 * @param stepId - The hint step ID
 */
hideHint(stepId: number): Promise<Hint>;

/**
 * Hide all hints on the page
 */
hideHints(): Promise<Hint>;

import introJs from "intro.js";

const hint = introJs.hint()
  .addHint({
    element: "#feature-1",
    hint: "This is feature 1"
  })
  .addHint({
    element: "#feature-2", 
    hint: "This is feature 2"
  });

await hint.render();

// Show/hide specific hints
hint.showHint(0);  // Show first hint
await hint.hideHint(1);  // Hide second hint

// Show/hide all hints
await hint.showHints();  // Show all hints
await hint.hideHints();  // Hide all hints

/**
 * Show hint dialog for a specific hint
 * @param stepId - The hint step ID
 */
showHintDialog(stepId: number): Promise<Hint>;

/**
 * Hide hint dialog from the page
 */
hideHintDialog(): Hint;

import introJs from "intro.js";

const hint = introJs.hint()
  .addHint({
    element: "#complex-feature",
    hint: "This feature has detailed options and settings available.",
    hintPosition: "top-middle"
  });

await hint.render();

// Show dialog for specific hint
await hint.showHintDialog(0);

// Hide dialog
hint.hideHintDialog();

/**
 * Set multiple hint options
 * @param partialOptions - Object containing option key-value pairs
 */
setOptions(partialOptions: Partial<HintOptions>): Hint;

/**
 * Set a single hint option
 * @param key - Option key
 * @param value - Option value
 */
setOption<K extends keyof HintOptions>(key: K, value: HintOptions[K]): Hint;

/**
 * Get a specific hint option value
 * @param key - Option key
 */
getOption<K extends keyof HintOptions>(key: K): HintOptions[K];

import introJs from "intro.js";

const hint = introJs.hint();

// Set multiple options
hint.setOptions({
  hintPosition: "top-middle",
  hintAnimation: true,
  hintAutoRefreshInterval: 50,
  hintButtonLabel: "Got it!"
});

// Set individual option
hint.setOption("hintShowButton", false);

// Get option value
const position = hint.getOption("hintPosition");

/**
 * Enable hint auto-refresh on page scroll and resize
 */
enableHintAutoRefresh(): Hint;

/**
 * Disable hint auto-refresh on page scroll and resize
 */
disableHintAutoRefresh(): Hint;

/**
 * Enable closing dialog when user clicks outside the hint
 */
enableCloseDialogOnWindowClick(): void;

/**
 * Disable closing dialog when user clicks outside the hint
 */
disableCloseDialogOnWindowClick(): void;

/**
 * Clone the hint instance
 */
clone(): Hint;

/**
 * Get the target element for hints
 */
getTargetElement(): HTMLElement;

/**
 * Get specific callback function
 * @param callbackName - The name of the callback
 */
callback<K extends keyof HintCallbacks>(callbackName: K): HintCallbacks[K] | undefined;

interface HintItem {
  /** Target element for the hint */
  element?: HTMLElement | string | null;
  /** Hint content text */
  hint?: string;
  /** Position of the hint icon relative to the target element */
  hintPosition: HintPosition;
  /** Position of the tooltip when hint is clicked */
  position: TooltipPosition;
  /** Custom CSS class for the hint tooltip */
  tooltipClass?: string;
  /** Whether to animate the hint icon */
  hintAnimation?: boolean;
  /** Internal tooltip element reference (set automatically) */
  hintTooltipElement?: HTMLElement;
  /** Internal active state (managed automatically) */
  isActive?: boolean;
}

import introJs from "intro.js";

const hint = introJs.hint();

// Complete hint definition
hint.addHint({
  element: "#advanced-settings",
  hint: "Configure advanced options and preferences for this feature.",
  hintPosition: "top-right",
  position: "bottom-left-aligned", 
  tooltipClass: "custom-hint-tooltip",
  hintAnimation: true
});

await hint.render();

/**
 * @deprecated Use render() instead
 */
addHints(): Promise<Hint>;

/**
 * @deprecated Use destroy() instead  
 */
removeHints(): Hint;

/**
 * @deprecated Use onHintsAdded instead
 */
onhintsadded(callback: hintsAddedCallback): Hint;

/**
 * @deprecated Use onHintClick instead
 */
onhintclick(callback: hintClickCallback): Hint;

/**
 * @deprecated Use onHintClose instead
 */
onhintclose(callback: hintCloseCallback): Hint;

// Old (deprecated)
await hint.addHints();
hint.removeHints();

// New (recommended)
await hint.render();
hint.destroy();