Utility Functions

/**
 * Media query utility for responsive breakpoint detection
 */
interface MediaQuery {
  /** Array of available media queries */
  queries: any[];
  
  /** Current active breakpoint name */
  current: string;
  
  /** Check if current breakpoint is at least the specified size */
  atLeast(size: string): boolean;
  
  /** Check if current breakpoint is exactly the specified size */
  only(size: string): boolean;
  
  /** Check if current breakpoint is up to the specified size */
  upTo(size: string): boolean;
  
  /** Check if current breakpoint is the specified size */
  is(size: string): boolean;
  
  /** Get media query string for specified size */
  get(size: string): string | null;
  
  /** Get next larger breakpoint name */
  next(size: string): string | null;
}

// Accessed via Foundation.MediaQuery
Foundation.MediaQuery.current; // 'small', 'medium', 'large', etc.
Foundation.MediaQuery.atLeast('medium'); // true if medium or larger
Foundation.MediaQuery.only('large'); // true if exactly large

// Check current breakpoint
if (Foundation.MediaQuery.current === 'small') {
  // Mobile-specific code
}

// Responsive behavior
if (Foundation.MediaQuery.atLeast('medium')) {
  // Tablet and desktop code
} else {
  // Mobile code
}

// Listen for breakpoint changes
$(window).on('changed.zf.mediaquery', function(event, newSize, oldSize) {
  console.log('Breakpoint changed from', oldSize, 'to', newSize);
});

/**
 * Box utility for element positioning and dimension calculations
 */
interface Box {
  /** 
   * Check if element is touching or overlapping another element
   * @param element - Element to check
   * @param parent - Parent/boundary element
   * @param lrOnly - Check only left/right positioning
   * @param tbOnly - Check only top/bottom positioning
   */
  ImNotTouchingYou(element: Object, parent?: Object, lrOnly?: boolean, tbOnly?: boolean): boolean;
  
  /**
   * Calculate overlap area between elements
   * @param element - Element to check
   * @param parent - Parent/boundary element  
   * @param lrOnly - Check only left/right overlap
   * @param tbOnly - Check only top/bottom overlap
   * @param ignoreBottom - Ignore bottom boundary
   */
  OverlapArea(element: Object, parent?: Object, lrOnly?: boolean, tbOnly?: boolean, ignoreBottom?: boolean): number;
  
  /**
   * Get element dimensions and position
   * @param element - Element to measure
   */
  GetDimensions(element: Object): Object;
  
  /**
   * Calculate explicit positioning offsets
   * @param element - Element to position
   * @param anchor - Anchor element
   * @param position - Desired position
   * @param alignment - Desired alignment
   * @param vOffset - Vertical offset
   * @param hOffset - Horizontal offset
   * @param isOverflow - Handle overflow
   */
  GetExplicitOffsets(element: any, anchor: any, position: string, alignment: any, vOffset: number, hOffset: number, isOverflow: boolean): Object;
}

// Accessed via Foundation.Box
const dimensions = Foundation.Box.GetDimensions($('#my-element'));
const isColliding = Foundation.Box.ImNotTouchingYou($('#dropdown'), $('#container'));

// Get element dimensions
const $element = $('#my-element');
const dims = Foundation.Box.GetDimensions($element);
console.log('Width:', dims.width, 'Height:', dims.height);
console.log('Position:', dims.offset.left, dims.offset.top);

// Check collision detection
const $dropdown = $('#my-dropdown');
const $container = $('.container');
const isNotColliding = Foundation.Box.ImNotTouchingYou($dropdown, $container);

if (!isNotColliding) {
  // Reposition dropdown
  $dropdown.addClass('position-alternative');
}

// Calculate positioning for tooltips/dropdowns
const offsets = Foundation.Box.GetExplicitOffsets(
  $dropdown,    // Element to position
  $trigger,     // Anchor element
  'bottom',     // Position below
  'center',     // Center alignment
  10,           // 10px vertical offset
  0,            // No horizontal offset
  false         // Don't handle overflow
);

/**
 * Keyboard utility for key event handling and focus management
 */
interface Keyboard {
  /**
   * Parse keyboard event and return key name
   * @param event - Keyboard event object
   */
  parseKey(event: any): string;
  
  /**
   * Handle keyboard event for component
   * @param event - Keyboard event
   * @param component - Component name
   * @param functions - Function map for keys
   */
  handleKey(event: any, component: any, functions: any): void;
  
  /**
   * Find focusable elements within container
   * @param element - Container element
   */
  findFocusable(element: JQuery): Object;
  
  /**
   * Register keyboard commands for component
   * @param componentName - Name of component
   * @param cmds - Command mappings
   */
  register(componentName: any, cmds: any): void;
  
  /**
   * Trap focus within element
   * @param element - Element to trap focus in
   */
  trapFocus(element: JQuery): void;
  
  /**
   * Release focus trap
   * @param element - Element to release focus from
   */
  releaseFocus(element: JQuery): void;
}

// Accessed via Foundation.Keyboard
Foundation.Keyboard.trapFocus($('#modal-content'));
const focusable = Foundation.Keyboard.findFocusable($('#container'));

// Handle keyboard navigation
$(document).on('keydown', function(e) {
  const key = Foundation.Keyboard.parseKey(e);
  
  if (key === 'ESCAPE') {
    // Close active modal/dropdown
    $('.reveal.is-active').foundation('close');
  }
});

// Trap focus in modal
$('#my-modal').on('open.zf.reveal', function() {
  Foundation.Keyboard.trapFocus($(this));
});

$('#my-modal').on('close.zf.reveal', function() {
  Foundation.Keyboard.releaseFocus($(this));
});

// Find all focusable elements
const $container = $('#navigation');
const focusableElements = Foundation.Keyboard.findFocusable($container);
console.log('Found', focusableElements.length, 'focusable elements');

// Register custom keyboard commands
Foundation.Keyboard.register('MyComponent', {
  'ENTER': 'activate',
  'SPACE': 'activate', 
  'ARROW_UP': 'previous',
  'ARROW_DOWN': 'next',
  'ESCAPE': 'close'
});

/**
 * Motion utility for animations and transitions
 */
interface Motion {
  /**
   * Animate element in with specified animation
   * @param element - Element to animate
   * @param animation - Animation class or config
   * @param cb - Callback function
   */
  animateIn(element: Object, animation: any, cb: Function): void;
  
  /**
   * Animate element out with specified animation
   * @param element - Element to animate
   * @param animation - Animation class or config
   * @param cb - Callback function
   */
  animateOut(element: Object, animation: any, cb: Function): void;
}

/**
 * Move utility for advanced motion controls
 */
interface Move {
  // Advanced motion control methods
}

// Accessed via Foundation.Motion
Foundation.Motion.animateIn($('#modal'), 'fade-in', function() {
  console.log('Animation complete');
});

/**
 * Timer utility for managing timed operations
 */
interface Timer {
  /** Start the timer */
  start(): void;
  
  /** Restart the timer */
  restart(): void;
  
  /** Pause the timer */
  pause(): void;
}

// Create and manage timers
const timer = new Foundation.Timer($('#my-element'), {
  duration: 5000,
  infinite: false
}, function() {
  console.log('Timer completed');
});

timer.start();

// Pause on hover
$('#my-element').hover(
  function() { timer.pause(); },
  function() { timer.restart(); }
);

/**
 * Touch utility for touch and swipe events
 */
interface Touch {
  /**
   * Setup spot swipe detection
   * @param event - Touch event
   */
  setupSpotSwipe(event: Object): void;
  
  /**
   * Setup touch event handler
   * @param event - Touch event
   */
  setupTouchHandler(event: Object): void;
  
  /**
   * Initialize touch utilities
   * @param event - Touch event
   */
  init(event: Object): void;
}

// Touch is auto-initialized
// Foundation.Touch.init($);

// Listen for swipe events (automatically handled by Foundation)
$('#swipeable').on('swipeleft swiperight', function(e) {
  if (e.type === 'swipeleft') {
    // Handle left swipe
    console.log('Swiped left');
  } else {
    // Handle right swipe  
    console.log('Swiped right');
  }
});

/**
 * Nest utility for menu structure management
 */
interface Nest {
  /**
   * Add nesting structure to menu
   * @param menu - Menu element
   * @param type - Menu type
   */
  Feather(menu: any, type: any): void;
  
  /**
   * Remove nesting structure from menu
   * @param menu - Menu element
   * @param type - Menu type
   */
  Burn(menu: any, type: any): void;
}

// Used internally by menu components
Foundation.Nest.Feather($('#dropdown-menu'), 'dropdown');

/**
 * Image loading utility
 * @param images - Images to check
 * @param callback - Callback when loaded
 */
function onImagesLoaded(images: any, callback: Function): void;

/**
 * Core utility functions available on Foundation object
 */
interface FoundationCore {
  /** Check if RTL mode is active */
  rtl(): boolean;
  
  /** Generate unique ID string */
  GetYoDigits(length: number, namespace?: string): string;
  
  /** Get appropriate transition end event name */
  transitionend(element: JQuery): any;
  
  /** Escape string for regex use */
  RegExpEscape(str: string): string;
  
  /** Handle element load events */
  onLoad(elem: any, handler: any): string;
}

// Accessed directly on Foundation
Foundation.rtl(); // Check RTL mode
Foundation.GetYoDigits(6, 'modal'); // Generate unique ID
Foundation.RegExpEscape('special.chars'); // Escape for regex

// Wait for images to load
Foundation.onImagesLoaded($('#gallery img'), function() {
  console.log('All images loaded');
  // Initialize image-dependent components
});

// Generate unique IDs
const uniqueId = Foundation.GetYoDigits(8, 'dropdown');
$('#dynamic-dropdown').attr('id', uniqueId);

// Handle transitions
const transitionEnd = Foundation.transitionend($('#animated-element'));
$('#animated-element').on(transitionEnd, function() {
  console.log('Transition completed');
});

// RTL support
if (Foundation.rtl()) {
  // RTL-specific positioning
  $('.dropdown-pane').addClass('position-right');
}

// Example: Custom dropdown with utilities
class CustomDropdown {
  constructor(element, options) {
    this.$element = element;
    this.options = options;
    this.id = Foundation.GetYoDigits(6, 'custom-dropdown');
    
    this._init();
  }
  
  _init() {
    // Use keyboard utility for navigation
    Foundation.Keyboard.register('CustomDropdown', {
      'ENTER': 'toggle',
      'SPACE': 'toggle',
      'ESCAPE': 'close'
    });
    
    this._events();
  }
  
  _events() {
    // Handle keyboard events
    this.$element.on('keydown.zf.customdropdown', (e) => {
      Foundation.Keyboard.handleKey(e, 'CustomDropdown', {
        toggle: () => this.toggle(),
        close: () => this.close()
      });
    });
    
    // Handle responsive changes
    $(window).on('changed.zf.mediaquery', () => {
      if (Foundation.MediaQuery.atLeast('medium')) {
        this._positionDropdown();
      }
    });
  }
  
  _positionDropdown() {
    // Use Box utility for positioning
    const isColliding = !Foundation.Box.ImNotTouchingYou(
      this.$dropdown, 
      $(window)
    );
    
    if (isColliding) {
      // Reposition if needed
      this.$dropdown.addClass('position-alternative');
    }
  }
}