Widgets

/**
 * Destroys the widget instance and removes all functionality
 */
$(...).widgetName('destroy');

/**
 * Disables the widget, preventing user interaction
 */
$(...).widgetName('disable');

/**
 * Enables the widget, allowing user interaction
 */
$(...).widgetName('enable');

/**
 * Gets or sets widget options
 * @param {string} key - Option name
 * @param {any} value - Option value (omit to get)
 * @returns {any} Option value when getting
 */
$(...).widgetName('option', key, value);

/**
 * Refreshes the widget's visual state
 */
$(...).widgetName('refresh');

/**
 * Returns the main widget element
 * @returns {jQuery} Widget element
 */
$(...).widgetName('widget');

/**
 * Creates an accordion widget
 * @param {AccordionOptions} options - Configuration options
 */
$(...).accordion(options);

/**
 * Refreshes the accordion heights and recalculates
 */
$(...).accordion('refresh');

interface AccordionOptions {
  active?: number | boolean;           // Initially active panel (0-based index or false for closed)
  animate?: boolean | number | string | object; // Animation settings
  classes?: {                         // CSS classes to apply
    'ui-accordion'?: string;
    'ui-accordion-header'?: string;
    'ui-accordion-content'?: string;
  };
  collapsible?: boolean;              // Allow all panels to be closed
  event?: string;                     // Event that triggers panel opening
  header?: string;                    // Selector for header elements
  heightStyle?: 'auto' | 'fill' | 'content'; // How to calculate heights
  icons?: {                           // Icons for headers
    header?: string;
    activeHeader?: string;
  };
}

/**
 * Creates an autocomplete widget
 * @param {AutocompleteOptions} options - Configuration options
 */
$(...).autocomplete(options);

/**
 * Closes the autocomplete menu
 */
$(...).autocomplete('close');

/**
 * Triggers a search programmatically
 * @param {string} value - Value to search for
 */
$(...).autocomplete('search', value);

interface AutocompleteOptions {
  appendTo?: string | Element;        // Element to append menu to
  autoFocus?: boolean;               // Auto-focus first item
  delay?: number;                    // Delay in milliseconds before triggering search
  disabled?: boolean;                // Disable the widget
  minLength?: number;                // Minimum characters before triggering search
  position?: object;                 // Position options for menu
  source: string | Array | Function; // Data source for suggestions
}

/**
 * Creates a button widget
 * @param {ButtonOptions} options - Configuration options
 */
$(...).button(options);

/**
 * Refreshes the button's visual state
 */
$(...).button('refresh');

interface ButtonOptions {
  classes?: object;                   // CSS classes to apply
  disabled?: boolean;                 // Disable the button
  icon?: string;                     // Icon class to display
  iconPosition?: 'beginning' | 'end'; // Icon position relative to text
  label?: string;                    // Button text
  showLabel?: boolean;               // Whether to show text with icon
}

/**
 * Creates a checkboxradio widget
 * @param {CheckboxradioOptions} options - Configuration options
 */
$(...).checkboxradio(options);

/**
 * Refreshes the widget's visual state
 */
$(...).checkboxradio('refresh');

interface CheckboxradioOptions {
  classes?: object;                   // CSS classes to apply
  disabled?: boolean;                 // Disable the control
  icon?: boolean;                    // Whether to show icon
  label?: string;                    // Label text
}

/**
 * Creates a controlgroup widget
 * @param {ControlgroupOptions} options - Configuration options
 */
$(...).controlgroup(options);

/**
 * Refreshes the control group layout
 */
$(...).controlgroup('refresh');

interface ControlgroupOptions {
  classes?: object;                   // CSS classes to apply
  direction?: 'horizontal' | 'vertical'; // Layout direction
  disabled?: boolean;                 // Disable all controls
  items?: object;                    // Control type definitions
}

/**
 * Creates a datepicker on an input element
 * @param {DatepickerOptions} options - Configuration options
 */
$(...).datepicker(options);

/**
 * Sets default datepicker options globally
 * @param {DatepickerOptions} settings - Default settings
 */
$.datepicker.setDefaults(settings);

/**
 * Formats a date object to string
 * @param {string} format - Date format string
 * @param {Date} date - Date to format
 * @param {object} settings - Additional settings
 * @returns {string} Formatted date string
 */
$.datepicker.formatDate(format, date, settings);

/**
 * Parses a date string to Date object
 * @param {string} format - Expected date format
 * @param {string} value - Date string to parse
 * @param {object} settings - Additional settings
 * @returns {Date} Parsed Date object
 */
$.datepicker.parseDate(format, value, settings);

interface DatepickerOptions {
  altField?: string;                  // Alternative field to update
  altFormat?: string;                 // Alternative field date format
  autoSize?: boolean;                 // Auto-resize input field
  buttonImage?: string;               // Button image URL
  buttonImageOnly?: boolean;          // Show only image, not button
  buttonText?: string;                // Button text
  changeMonth?: boolean;              // Show month dropdown
  changeYear?: boolean;               // Show year dropdown
  closeText?: string;                 // Close button text
  constrainInput?: boolean;           // Constrain input to date format
  currentText?: string;               // Current day button text
  dateFormat?: string;                // Date format string
  dayNames?: string[];                // Day names array
  dayNamesMin?: string[];             // Minimum day names array
  dayNamesShort?: string[];           // Short day names array
  defaultDate?: Date | number | string; // Default date to highlight
  duration?: string | number;         // Animation duration
  firstDay?: number;                  // First day of week (0=Sunday)
  gotoCurrent?: boolean;              // Go to current date
  hideIfNoPrevNext?: boolean;         // Hide prev/next if not applicable
  isRTL?: boolean;                   // Right-to-left reading
  maxDate?: Date | number | string;   // Maximum selectable date
  minDate?: Date | number | string;   // Minimum selectable date
  monthNames?: string[];              // Month names array
  monthNamesShort?: string[];         // Short month names array
  navigationAsDateFormat?: boolean;   // Format navigation as dates
  nextText?: string;                  // Next month button text
  numberOfMonths?: number | number[]; // Number of months to show
  prevText?: string;                  // Previous month button text
  selectOtherMonths?: boolean;        // Allow selection of other months
  shortYearCutoff?: number | string;  // Cutoff for short year format
  showAnim?: string;                  // Animation name
  showButtonPanel?: boolean;          // Show button panel
  showCurrentAtPos?: number;          // Position of current month
  showMonthAfterYear?: boolean;       // Show month after year
  showOn?: 'focus' | 'button' | 'both'; // When to show datepicker
  showOptions?: object;               // Animation options
  showOtherMonths?: boolean;          // Show other months
  showWeek?: boolean;                 // Show week numbers
  stepMonths?: number;                // Months to step
  weekHeader?: string;                // Week header text
  yearRange?: string;                 // Year range for dropdown
  yearSuffix?: string;                // Year suffix text
  beforeShow?: (input, inst) => object; // Callback before showing
  beforeShowDay?: (date) => [boolean, string]; // Callback for each day
  onChangeMonthYear?: (year, month, inst) => void; // Month/year change callback
  onClose?: (dateText, inst) => void; // Close callback
  onSelect?: (dateText, inst) => void; // Selection callback
}

/**
 * Creates a dialog widget
 * @param {DialogOptions} options - Configuration options
 */
$(...).dialog(options);

/**
 * Closes the dialog
 */
$(...).dialog('close');

/**
 * Checks if dialog is open
 * @returns {boolean} True if dialog is open
 */
$(...).dialog('isOpen');

/**
 * Moves dialog to top of z-index stack
 */
$(...).dialog('moveToTop');

/**
 * Opens the dialog
 */
$(...).dialog('open');

interface DialogOptions {
  appendTo?: string;                  // Element to append dialog to
  autoOpen?: boolean;                 // Open automatically on creation
  buttons?: object | Array;           // Button configuration
  classes?: object;                   // CSS classes to apply
  closeOnEscape?: boolean;            // Close on Escape key
  closeText?: string;                 // Close button text
  draggable?: boolean;                // Enable dragging
  height?: number | string;           // Dialog height
  hide?: boolean | number | string | object; // Hide animation
  maxHeight?: number;                 // Maximum height
  maxWidth?: number;                  // Maximum width
  minHeight?: number;                 // Minimum height
  minWidth?: number;                  // Minimum width
  modal?: boolean;                    // Modal dialog
  position?: object;                  // Position options
  resizable?: boolean;                // Enable resizing
  show?: boolean | number | string | object; // Show animation
  title?: string;                     // Dialog title
  width?: number | string;            // Dialog width
}

/**
 * Creates a menu widget
 * @param {MenuOptions} options - Configuration options
 */
$(...).menu(options);

/**
 * Removes focus from menu
 * @param {Event} event - Original event
 */
$(...).menu('blur', event);

/**
 * Collapses active submenu
 * @param {Event} event - Original event
 */
$(...).menu('collapse', event);

/**
 * Collapses all open submenus
 * @param {Event} event - Original event
 * @param {boolean} all - Whether to collapse all levels
 */
$(...).menu('collapseAll', event, all);

/**
 * Expands submenu under active item
 * @param {Event} event - Original event
 */
$(...).menu('expand', event);

/**
 * Sets focus to specified menu item
 * @param {Event} event - Original event
 * @param {jQuery} item - Menu item to focus
 */
$(...).menu('focus', event, item);

/**
 * Checks if focused item is first in menu
 * @returns {boolean} True if first item
 */
$(...).menu('isFirstItem');

/**
 * Checks if focused item is last in menu
 * @returns {boolean} True if last item
 */
$(...).menu('isLastItem');

/**
 * Moves focus to next menu item
 * @param {Event} event - Original event
 */
$(...).menu('next', event);

/**
 * Moves focus to next page of items
 * @param {Event} event - Original event
 */
$(...).menu('nextPage', event);

/**
 * Moves focus to previous menu item
 * @param {Event} event - Original event
 */
$(...).menu('previous', event);

/**
 * Moves focus to previous page of items
 * @param {Event} event - Original event
 */
$(...).menu('previousPage', event);

/**
 * Refreshes menu structure and submenus
 */
$(...).menu('refresh');

/**
 * Selects currently active menu item
 * @param {Event} event - Original event
 */
$(...).menu('select', event);

interface MenuOptions {
  classes?: object;                   // CSS classes to apply
  disabled?: boolean;                 // Disable the menu
  icons?: {                          // Icon configuration
    submenu?: string;                 // Submenu indicator icon
  };
  items?: string;                    // Selector for menu items
  menus?: string;                    // Selector for submenus
  position?: object;                 // Position options for submenus
  role?: string;                     // ARIA role for menu
}

/**
 * Creates a progressbar widget
 * @param {ProgressbarOptions} options - Configuration options
 */
$(...).progressbar(options);

/**
 * Gets current progress value
 * @returns {number} Current value
 */
$(...).progressbar('value');

/**
 * Sets progress value
 * @param {number} value - New progress value
 */
$(...).progressbar('value', value);

interface ProgressbarOptions {
  classes?: object;                   // CSS classes to apply
  disabled?: boolean;                 // Disable the progressbar
  max?: number;                      // Maximum value (default: 100)
  value?: number;                    // Current value (default: 0)
}

/**
 * Creates a selectmenu widget
 * @param {SelectmenuOptions} options - Configuration options
 */
$(...).selectmenu(options);

/**
 * Closes the selectmenu dropdown
 */
$(...).selectmenu('close');

/**
 * Returns the menu widget instance
 * @returns {jQuery} Menu widget
 */
$(...).selectmenu('menuWidget');

/**
 * Opens the selectmenu dropdown
 */
$(...).selectmenu('open');

/**
 * Refreshes options from underlying select element
 */
$(...).selectmenu('refresh');

interface SelectmenuOptions {
  appendTo?: string;                  // Element to append menu to
  classes?: object;                   // CSS classes to apply
  disabled?: boolean;                 // Disable the selectmenu
  icons?: {                          // Icon configuration
    button?: string;                  // Button icon
  };
  position?: object;                 // Position options for menu
  width?: number | string;           // Menu width
}

/**
 * Creates a slider widget
 * @param {SliderOptions} options - Configuration options
 */
$(...).slider(options);

/**
 * Gets current value (single handle slider)
 * @returns {number} Current value
 */
$(...).slider('value');

/**
 * Sets value (single handle slider)
 * @param {number} value - New value
 */
$(...).slider('value', value);

/**
 * Gets all values (multi-handle slider)
 * @returns {number[]} Array of values
 */
$(...).slider('values');

/**
 * Gets value at specific index (multi-handle slider)
 * @param {number} index - Handle index
 * @returns {number} Value at index
 */
$(...).slider('values', index);

/**
 * Sets value at specific index (multi-handle slider)
 * @param {number} index - Handle index
 * @param {number} value - New value
 */
$(...).slider('values', index, value);

/**
 * Sets all values (multi-handle slider)
 * @param {number[]} values - Array of new values
 */
$(...).slider('values', values);

interface SliderOptions {
  animate?: boolean | string | number; // Animation settings
  classes?: object;                   // CSS classes to apply
  disabled?: boolean;                 // Disable the slider
  max?: number;                      // Maximum value
  min?: number;                      // Minimum value
  orientation?: 'horizontal' | 'vertical'; // Slider orientation
  range?: boolean | 'min' | 'max';   // Range display
  step?: number;                     // Step size
  value?: number;                    // Initial value (single handle)
  values?: number[];                 // Initial values (multi-handle)
}

/**
 * Creates a spinner widget
 * @param {SpinnerOptions} options - Configuration options
 */
$(...).spinner(options);

/**
 * Decrements value by page amount
 * @param {number} pages - Number of pages to decrement
 */
$(...).spinner('pageDown', pages);

/**
 * Increments value by page amount
 * @param {number} pages - Number of pages to increment
 */
$(...).spinner('pageUp', pages);

/**
 * Decrements value by step amount
 * @param {number} steps - Number of steps to decrement
 */
$(...).spinner('stepDown', steps);

/**
 * Increments value by step amount
 * @param {number} steps - Number of steps to increment
 */
$(...).spinner('stepUp', steps);

/**
 * Gets current numeric value
 * @returns {number} Current value
 */
$(...).spinner('value');

/**
 * Sets numeric value
 * @param {number} value - New value
 */
$(...).spinner('value', value);

interface SpinnerOptions {
  classes?: object;                   // CSS classes to apply
  culture?: string;                   // Culture for number formatting
  disabled?: boolean;                 // Disable the spinner
  icons?: {                          // Icon configuration
    down?: string;                    // Down button icon
    up?: string;                      // Up button icon
  };
  incremental?: boolean | Function;   // Incremental spinning behavior
  max?: number;                      // Maximum value
  min?: number;                      // Minimum value
  numberFormat?: string;             // Number format string
  page?: number;                     // Page increment size
  step?: number;                     // Step increment size
}

/**
 * Creates a tabs widget
 * @param {TabsOptions} options - Configuration options
 */
$(...).tabs(options);

/**
 * Disables specified tab by index
 * @param {number} index - Tab index to disable
 */
$(...).tabs('disable', index);

/**
 * Enables specified tab by index
 * @param {number} index - Tab index to enable
 */
$(...).tabs('enable', index);

/**
 * Loads tab content via AJAX
 * @param {number} index - Tab index to load
 */
$(...).tabs('load', index);

/**
 * Processes added/removed tabs and refreshes
 */
$(...).tabs('refresh');

interface TabsOptions {
  active?: number | boolean;          // Initially active tab
  classes?: object;                   // CSS classes to apply
  collapsible?: boolean;              // Allow active tab to be deselected
  disabled?: boolean | number[];      // Disabled tabs
  event?: string;                     // Event that activates tab
  heightStyle?: 'auto' | 'fill' | 'content'; // Height calculation
  hide?: boolean | number | string | object; // Hide animation
  show?: boolean | number | string | object; // Show animation
}

/**
 * Creates a tooltip widget
 * @param {TooltipOptions} options - Configuration options
 */
$(...).tooltip(options);

/**
 * Closes tooltip programmatically
 * @param {Event} event - Original event
 */
$(...).tooltip('close', event);

/**
 * Opens tooltip programmatically
 * @param {Event} event - Original event
 */
$(...).tooltip('open', event);

interface TooltipOptions {
  classes?: object;                   // CSS classes to apply
  content?: string | Function;        // Tooltip content
  disabled?: boolean;                 // Disable the tooltip
  hide?: boolean | number | string | object; // Hide animation
  items?: string;                    // Selector for elements with tooltips
  position?: object;                 // Position options
  show?: boolean | number | string | object; // Show animation
  tooltipClass?: string;             // Additional CSS class for tooltip
  track?: boolean;                   // Track mouse movement
}

// Common widget event object
interface WidgetEvent {
  type: string;
  target: Element;
  currentTarget: Element;
  originalEvent?: Event;
  data?: any;
}

// Base widget options (inherited by all widgets)
interface BaseWidgetOptions {
  disabled?: boolean;
  classes?: { [key: string]: string };
}

// Widget method return types
type WidgetMethodReturn = jQuery | any;

// Animation options (used by multiple widgets)
interface AnimationOptions {
  effect?: string;
  duration?: number | string;
  easing?: string;
  complete?: () => void;
}