Utilities & Services

/**
 * Get or set global locale configuration
 * @param locale - Locale identifier (e.g., 'en', 'es', 'fr')
 */
function locale(locale?: string): string | void;

/**
 * Add custom locale configuration
 * @param locale - Locale identifier
 * @param options - Locale configuration object
 */
function addLocale(locale: string, options: LocaleOptions): void;

/**
 * Global PrimeReact API configuration object
 */
interface PrimeReactAPI {
  /** Global ripple effect toggle */
  ripple: boolean;
  /** Global input styling mode */
  inputStyle: 'outlined' | 'filled';
  /** Global locale setting */
  locale: string;
  /** Global append target for overlays */
  appendTo: HTMLElement | string | null;
  /** Automatic z-index management */
  autoZIndex: boolean;
  /** Base z-index value */
  zIndex: {
    modal: number;
    overlay: number;
    menu: number;
    tooltip: number;
  };
  /** Hide overlays on document scrolling */
  hideOverlaysOnDocumentScrolling: boolean;
  /** CSP nonce for inline styles */
  nonce: string | undefined;
  /** Null sort order for DataTable */
  nullSortOrder: 1 | -1;
  /** Global filter match mode options */
  filterMatchModeOptions: {
    text: FilterMatchModeOption[];
    numeric: FilterMatchModeOption[];
    date: FilterMatchModeOption[];
  };
}

interface LocaleOptions {
  firstDayOfWeek?: number;
  dayNames?: string[];
  dayNamesShort?: string[];
  dayNamesMin?: string[];
  monthNames?: string[];
  monthNamesShort?: string[];
  today?: string;
  clear?: string;
  dateFormat?: string;
  weekHeader?: string;
  [key: string]: any;
}

interface FilterMatchModeOption {
  label: string;
  value: string;
}

import { locale, addLocale, PrimeReactAPI } from "primereact/api";

// Set global locale
locale('en');

// Add custom locale
addLocale('custom', {
  firstDayOfWeek: 1,
  dayNames: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'],
  monthNames: ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'],
  today: 'Today',
  clear: 'Clear'
});

// Configure global settings
PrimeReactAPI.ripple = true;
PrimeReactAPI.inputStyle = 'outlined';
PrimeReactAPI.autoZIndex = true;

/**
 * Hook for managing event listeners with cleanup
 * @param options - Event listener configuration
 */
function useEventListener(options: EventListenerOptions): void;

interface EventListenerOptions {
  type: string;
  listener: EventListener;
  target?: EventTarget | null;
  options?: boolean | AddEventListenerOptions;
}

/**
 * Hook that runs effect only on updates, not on mount
 * @param fn - Effect function
 * @param deps - Dependency array
 */
function useUpdateEffect(fn: () => void | (() => void), deps: React.DependencyList): void;

/**
 * Hook that returns the previous value of a variable
 * @param value - Current value
 * @returns Previous value
 */
function usePrevious<T>(value: T): T | undefined;

/**
 * Hook for detecting clicks outside a component
 * @param ref - Reference to the component element
 * @param callback - Function to call when outside click occurs
 */
function useClickOutside<T extends HTMLElement>(
  ref: React.RefObject<T>,
  callback: () => void
): void;

/**
 * Hook for managing resize event listeners
 * @param listener - Resize event handler
 * @param target - Target element (defaults to window)
 */
function useResizeListener(listener: () => void, target?: EventTarget): void;

/**
 * Hook for handling overlay scroll events
 * @param options - Scroll handling configuration
 */
function useOverlayScrollListener(options: OverlayScrollListenerOptions): void;

interface OverlayScrollListenerOptions {
  target: React.RefObject<HTMLElement>;
  overlay: React.RefObject<HTMLElement>;
  listener: () => void;
  when?: boolean;
}

/**
 * Hook for managing display order of overlays
 * @param overlayRef - Reference to overlay element
 * @param visible - Visibility state
 */
function useDisplayOrder(overlayRef: React.RefObject<HTMLElement>, visible: boolean): void;

/**
 * Effect hook that only runs on component unmount
 * @param fn - Cleanup function
 */
function useUnmountEffect(fn: () => void): void;

/**
 * Object manipulation utilities
 */
class ObjectUtils {
  /** Check if value is empty (null, undefined, empty string/array/object) */
  static isEmpty(value: any): boolean;
  
  /** Check if value is not empty */
  static isNotEmpty(value: any): boolean;
  
  /** Deep merge objects */
  static merge(target: object, ...sources: object[]): object;
  
  /** Get nested property value by path */
  static resolveFieldData(data: any, field: string): any;
  
  /** Check if objects are equal */
  static equals(obj1: any, obj2: any, field?: string): boolean;
  
  /** Deep clone object */
  static deepEquals(a: any, b: any): boolean;
  
  /** Remove accents from string */
  static removeAccents(str: string): string;
  
  /** Check if value is array */
  static isArray(value: any): boolean;
  
  /** Check if value is date */
  static isDate(value: any): boolean;
  
  /** Check if value is function */
  static isFunction(value: any): boolean;
  
  /** Check if value is object */
  static isObject(value: any): boolean;
}

/**
 * DOM manipulation utilities
 */
class DomHandler {
  /** Add CSS class to element */
  static addClass(element: Element, className: string): void;
  
  /** Remove CSS class from element */
  static removeClass(element: Element, className: string): void;
  
  /** Check if element has CSS class */
  static hasClass(element: Element, className: string): boolean;
  
  /** Find single element by selector */
  static find(element: Element, selector: string): Element;
  
  /** Find multiple elements by selector */
  static findSingle(element: Element, selector: string): Element;
  
  /** Get element index within parent */
  static index(element: Element): number;
  
  /** Get element offset position */
  static getOffset(element: Element): { top: number; left: number };
  
  /** Get element width */
  static getWidth(element: Element): number;
  
  /** Get element height */
  static getHeight(element: Element): number;
  
  /** Get scrollbar width */
  static calculateScrollbarWidth(): number;
  
  /** Invoke function on next animation frame */
  static invokeElementMethod(element: Element, methodName: string, args?: any[]): any;
  
  /** Check if element is visible */
  static isVisible(element: Element): boolean;
  
  /** Get viewport */
  static getViewport(): { width: number; height: number };
  
  /** Get element outline width */
  static getOuterWidth(element: Element, margin?: boolean): number;
  
  /** Get element outline height */
  static getOuterHeight(element: Element, margin?: boolean): number;
  
  /** Fade in element */
  static fadeIn(element: Element, duration: number): void;
  
  /** Fade out element */
  static fadeOut(element: Element, duration: number): void;
  
  /** Get user agent */
  static getUserAgent(): string;
  
  /** Check if browser */
  static isIOS(): boolean;
  static isAndroid(): boolean;
  static isTouchDevice(): boolean;
}

/**
 * Z-index management utilities
 */
class ZIndexUtils {
  /** Get current z-index */
  static getCurrent(): number;
  
  /** Get new z-index */
  static getNext(): number;
  
  /** Set z-index for element */
  static set(key: string, element: HTMLElement, baseZIndex?: number): void;
  
  /** Clear z-index for element */
  static clear(element: HTMLElement): void;
}

/**
 * Generate unique component ID
 * @param prefix - Optional prefix for the ID
 * @returns Unique identifier string
 */
function UniqueComponentId(prefix?: string): string;

/**
 * Global event bus for component communication
 */
class EventBus {
  /** Subscribe to event */
  static on(event: string, callback: Function): void;
  
  /** Unsubscribe from event */
  static off(event: string, callback: Function): void;
  
  /** Emit event */
  static emit(event: string, ...args: any[]): void;
}

/**
 * React portal component for rendering outside component tree
 * @param props - Portal configuration options
 * @returns JSX element
 */
function Portal(props: PortalProps): JSX.Element;

interface PortalProps {
  /** Content to portal */
  children?: React.ReactNode;
  /** Target element or selector */
  element?: HTMLElement | string;
  /** Append to document body */
  appendTo?: HTMLElement | string;
  /** Visible state */
  visible?: boolean;
  /** Show event handler */
  onMounted?: (el: HTMLElement) => void;
  /** Hide event handler */
  onUnmounted?: (el: HTMLElement) => void;
}

/**
 * CSS transition wrapper component
 * @param props - CSSTransition configuration options
 * @returns JSX element
 */
function CSSTransition(props: CSSTransitionProps): JSX.Element;

interface CSSTransitionProps {
  /** Child element to animate */
  children?: React.ReactNode;
  /** Transition enabled */
  in?: boolean;
  /** CSS class prefix for transition states */
  classNames?: string;
  /** Transition timeout */
  timeout?: number;
  /** Unmount on exit */
  unmountOnExit?: boolean;
  /** Enter transition handler */
  onEnter?: (node: HTMLElement) => void;
  /** Enter transition complete handler */
  onEntered?: (node: HTMLElement) => void;
  /** Exit transition handler */
  onExit?: (node: HTMLElement) => void;
  /** Exit transition complete handler */
  onExited?: (node: HTMLElement) => void;
}

/**
 * Material design ripple effect component
 * @param props - Ripple configuration options
 * @returns JSX element
 */
function Ripple(props: RippleProps): JSX.Element;

interface RippleProps {
  /** CSS class name */
  className?: string;
  /** Passthrough options */
  pt?: PassThroughOptions;
}

/**
 * Tooltip component for contextual information
 * @param props - Tooltip configuration options
 * @returns JSX element
 */
function Tooltip(props: TooltipProps): JSX.Element;

interface TooltipProps {
  /** Target element selector or reference */
  target?: string | React.RefObject<HTMLElement>;
  /** Tooltip content */
  content?: string;
  /** Position relative to target */
  position?: 'right' | 'left' | 'top' | 'bottom';
  /** Event that triggers tooltip */
  event?: 'hover' | 'focus';
  /** Hide event */
  hideEvent?: 'hover' | 'blur';
  /** Show delay in milliseconds */
  showDelay?: number;
  /** Hide delay in milliseconds */
  hideDelay?: number;
  /** Auto hide enabled */
  autoHide?: boolean;
  /** Show on disabled elements */
  showOnDisabled?: boolean;
  /** CSS class name */
  className?: string;
  /** Passthrough options */
  pt?: PassThroughOptions;
}

/**
 * Global tooltip options interface
 */
interface TooltipOptions {
  tooltip?: string;
  tooltipOptions?: {
    className?: string;
    position?: 'right' | 'left' | 'top' | 'bottom';
    event?: 'hover' | 'focus';
    showDelay?: number;
    hideDelay?: number;
  };
}

/**
 * Overlay management service
 */
class OverlayService {
  /** Show overlay */
  static show(overlay: HTMLElement, target: HTMLElement, options?: OverlayOptions): void;
  
  /** Hide overlay */
  static hide(overlay: HTMLElement): void;
  
  /** Check if overlay is visible */
  static isVisible(overlay: HTMLElement): boolean;
}

interface OverlayOptions {
  position?: 'center' | 'top' | 'bottom' | 'left' | 'right';
  modal?: boolean;
  dismissable?: boolean;
  showTransition?: string;
  hideTransition?: string;
}

/**
 * Terminal service for Terminal component
 */
class TerminalService {
  /** Send command to terminal */
  static sendCommand(command: string): void;
  
  /** Subscribe to command events */
  static on(event: 'command' | 'response', callback: Function): void;
  
  /** Unsubscribe from events */
  static off(event: 'command' | 'response', callback: Function): void;
}