Core Positioning

/**
 * Creates a new Tether instance for positioning an element relative to a target
 * @param options - Configuration object for the tether
 */
constructor(options: TetherOptions);

interface TetherOptions {
  /** Element to be positioned (CSS selector or DOM element) */
  element: string | HTMLElement;
  /** Target element to attach to (CSS selector or DOM element) */
  target: string | HTMLElement;
  /** Attachment point on the element being positioned */
  attachment: string;
  /** Attachment point on the target element (defaults to 'auto auto') */
  targetAttachment?: string;
  /** Offset from the attachment point (defaults to '0 0') */
  offset?: string;
  /** Offset from the target attachment point (defaults to '0 0') */
  targetOffset?: string;
  /** Whether the tether is initially enabled (defaults to true) */
  enabled?: boolean;
  /** Prefix for generated CSS classes (defaults to 'tether') */
  classPrefix?: string;
  /** Element to append the positioned element to (defaults to document.body) */
  bodyElement?: HTMLElement | string;
  /** Array of constraint objects for boundary checking */
  constraints?: ConstraintOptions[];
  /** Performance and positioning optimizations */
  optimizations?: OptimizationOptions;
  /** Whether to add classes to the target element (defaults to true) */
  addTargetClasses?: boolean;
  /** Target modifier for special target behaviors */
  targetModifier?: string;
  /** Manual positioning shift options */
  shift?: string | ShiftOptions | Function;
  /** Custom CSS class overrides for specific element states */
  classes?: {
    [key: string]: string | false;
  };
}

import Tether from "tether";

// Basic positioning
const tether = new Tether({
  element: '#tooltip',
  target: '#button',
  attachment: 'top center',
  targetAttachment: 'bottom center'
});

// With offsets and custom classes
const advancedTether = new Tether({
  element: document.querySelector('.dropdown'),
  target: '.trigger',
  attachment: 'top left',
  targetAttachment: 'bottom left',
  offset: '0 10px',
  classPrefix: 'my-tether',
  bodyElement: document.querySelector('.container')
});

// With manual shift adjustment
const shiftedTether = new Tether({
  element: '.popover',
  target: '.anchor',
  attachment: 'top center',
  targetAttachment: 'bottom center',
  shift: '10px 5px'  // Shift position by 10px down, 5px right
});

// With dynamic shift function
const dynamicTether = new Tether({
  element: '.tooltip',
  target: '.help-icon',
  attachment: 'top center',
  targetAttachment: 'bottom center',
  shift: function(pos) {
    // Custom shift logic based on current position
    return { top: pos.top - 5, left: pos.left + 10 };
  }
});

/**
 * Calculates and applies positioning for the tethered element
 * @param flushChanges - Whether to immediately apply changes (defaults to true)
 * @returns Boolean indicating if positioning was successful
 */
position(flushChanges?: boolean): boolean;

/**
 * Enables the tether and starts positioning
 * @param pos - Whether to position immediately after enabling (defaults to true)
 */
enable(pos?: boolean): void;

/**
 * Disables tether positioning and removes event listeners
 */
disable(): void;

/**
 * Completely destroys the tether instance
 * Removes all applied classes and cleans up event listeners
 */
destroy(): void;

/**
 * Updates tether configuration options
 * @param options - New options to merge with existing configuration
 * @param pos - Whether to reposition after setting options (defaults to true)
 */
setOptions(options: Partial<TetherOptions>, pos?: boolean): void;

// Update attachment points dynamically
tether.setOptions({
  attachment: 'bottom center',
  targetAttachment: 'top center',
  offset: '5px 0'
});

/**
 * Gets the bounding rectangle of the target element
 * Considers target modifiers like 'visible' and 'scroll-handle'
 * @returns Bounds object with position and dimensions
 */
getTargetBounds(): BoundsObject;

/**
 * Clears the internal positioning cache
 * Useful when DOM has changed and cache needs refreshing
 */
clearCache(): void;

/**
 * Caches computed values for performance optimization
 * @param key - Cache key
 * @param getter - Function to compute the cached value
 * @returns Cached or computed value
 */
cache(key: string, getter: Function): any;

/**
 * Updates CSS classes based on current attachment points
 * @param elementAttach - Element attachment configuration
 * @param targetAttach - Target attachment configuration
 */
updateAttachClasses(elementAttach?: AttachmentConfig, targetAttach?: AttachmentConfig): void;

/**
 * Moves the element to the specified position with optimization handling
 * Internal method that applies calculated positioning with performance optimizations
 * @param pos - Position data containing page, viewport, and offset coordinates
 */
move(pos: PositionData): void;

interface BoundsObject {
  top: number;
  left: number;
  right: number;
  bottom: number;
  width: number;
  height: number;
}

interface AttachmentConfig {
  top: string | false;
  left: string | false;
}

interface ShiftOptions {
  top: number;
  left: number;
}

interface OffsetObject {
  top: number;
  left: number;
}

interface PositionData {
  page: {
    top: number;
    left: number;
    bottom?: number;
    right?: number;
  };
  viewport: {
    top: number;
    left: number;
    bottom: number;
    right: number;
  };
  offset?: {
    top: number;
    left: number;
  };
}