Composables and Hooks

/**
 * Get component namespace for BEM CSS class generation
 * @param block - Block name for BEM methodology
 * @returns Namespace utilities for generating CSS classes
 */
declare function useNamespace(block: string): NamespaceReturn;

interface NamespaceReturn {
  /** Generate namespace */
  namespace: ComputedRef<string>;
  /** Generate block class */
  b: (blockSuffix?: string) => string;
  /** Generate element class */
  e: (element?: string) => string;
  /** Generate modifier class */
  m: (modifier?: string) => string;
  /** Generate block element class */
  be: (block?: string, element?: string) => string;
  /** Generate element modifier class */
  em: (element?: string, modifier?: string) => string;
  /** Generate block modifier class */
  bm: (block?: string, modifier?: string) => string;
  /** Generate block element modifier class */
  bem: (block?: string, element?: string, modifier?: string) => string;
  /** Check if CSS variable */
  is: (name: string, state?: boolean | undefined) => string;
  /** Generate CSS variable */
  cssVar: (object: Record<string, string>) => Record<string, string>;
  /** Generate CSS variable with namespace */
  cssVarName: (name: string) => string;
  /** Generate CSS variable block */
  cssVarBlock: (object: Record<string, string>) => Record<string, string>;
  /** Generate CSS variable block with name */
  cssVarBlockName: (name: string) => string;
}

/**
 * Get component size with inheritance from parent providers
 * @param fallback - Fallback size if none provided
 * @returns Component size context
 */
declare function useSize(fallback?: ComponentSize): SizeContext;

interface SizeContext {
  /** Current component size */
  size: ComputedRef<ComponentSize>;
}

/**
 * Generate unique IDs for components
 * @param deterministicId - Optional deterministic ID
 * @returns Unique ID getter
 */
declare function useId(deterministicId?: string): ComputedRef<string>;

/**
 * Z-index management system
 * @returns Z-index utilities
 */
declare function useZIndex(): ZIndexContext;

interface ZIndexContext {
  /** Get initial z-index */
  initialZIndex: ComputedRef<number>;
  /** Get current z-index */
  currentZIndex: ComputedRef<number>;
  /** Get next z-index */
  nextZIndex: () => number;
}

/**
 * Component attributes filtering
 * @param params - Configuration parameters
 * @returns Filtered attributes
 */
declare function useAttrs(params?: AttrsParams): ComputedRef<Record<string, unknown>>;

interface AttrsParams {
  /** Exclude keys from attrs */
  excludeKeys?: string[];
  /** Exclude default keys */
  excludeListeners?: boolean;
}

/**
 * Internationalization hook for component translations
 * @returns Locale context with translation function
 */
declare function useLocale(): LocaleContext;

interface LocaleContext {
  /** Translation function */
  t: (path: string, ...args: any[]) => string;
  /** Current locale object */
  locale: ComputedRef<Language>;
}

interface Language {
  name: string;
  el: Record<string, any>;
}

/**
 * Focus management for components
 * @param target - Target element or ref
 * @param options - Focus options
 * @returns Focus utilities
 */
declare function useFocus(
  target: MaybeElementRef,
  options?: FocusOptions
): FocusReturn;

interface FocusReturn {
  /** Whether element is focused */
  focused: ComputedRef<boolean>;
  /** Focus the element */
  focus: () => void;
  /** Blur the element */
  blur: () => void;
}

interface FocusOptions {
  /** Initial focused state */
  initialValue?: boolean;
  /** Focus on mount */
  focusOnMount?: boolean;
}

/**
 * Focus controller for advanced focus management
 * @param options - Controller options
 * @returns Focus controller utilities
 */
declare function useFocusController(): FocusControllerReturn;

interface FocusControllerReturn {
  /** Trap focus within container */
  trapFocus: () => void;
  /** Release focus trap */
  releaseFocus: () => void;
  /** Focus first element */
  focusFirstElement: () => void;
  /** Focus last element */
  focusLastElement: () => void;
}

/**
 * Escape key handling
 * @param callback - Callback on escape key press
 * @returns Cleanup function
 */
declare function useEscapeKeydown(callback?: (event: KeyboardEvent) => void): void;

/**
 * Input composition handling for IME
 * @param emit - Component emit function
 * @returns Composition event handlers
 */
declare function useComposition(emit: (event: string, ...args: any[]) => void): CompositionReturn;

interface CompositionReturn {
  /** Composition start handler */
  handleCompositionStart: (event: CompositionEvent) => void;
  /** Composition update handler */
  handleCompositionUpdate: (event: CompositionEvent) => void;
  /** Composition end handler */
  handleCompositionEnd: (event: CompositionEvent) => void;
  /** Whether composing */
  isComposing: Ref<boolean>;
}

/**
 * Calculate input width based on content
 * @param input - Input element reference
 * @param options - Calculation options
 * @returns Width calculation utilities
 */
declare function useCalcInputWidth(
  input: Ref<HTMLInputElement | undefined>,
  options?: CalcInputWidthOptions
): CalcInputWidthReturn;

interface CalcInputWidthOptions {
  /** Minimum width */
  minWidth?: number;
  /** Maximum width */
  maxWidth?: number;
  /** Extra padding */
  padding?: number;
}

interface CalcInputWidthReturn {
  /** Calculated width */
  width: ComputedRef<string>;
  /** Update width calculation */
  update: () => void;
}

/**
 * Empty values handling for forms
 * @param props - Component props
 * @param key - Value key to check
 * @returns Empty value utilities  
 */
declare function useEmptyValues(props: any, key?: string): EmptyValuesReturn;

interface EmptyValuesReturn {
  /** Whether value is empty */
  isEmpty: ComputedRef<boolean>;
  /** Empty value */
  emptyValue: ComputedRef<any>;
}

/**
 * Popper.js integration for tooltips and dropdowns
 * @param options - Popper options
 * @returns Popper utilities
 */
declare function usePopper(options: PopperOptions): PopperReturn;

interface PopperOptions {
  /** Reference element */
  referenceEl: MaybeElementRef;
  /** Popper element */
  popperEl: MaybeElementRef;
  /** Popper placement */
  placement?: string;
  /** Popper offset */
  offset?: [number, number];
  /** Show arrow */
  showArrow?: boolean;
}

interface PopperReturn {
  /** Update popper position */
  update: () => void;
  /** Destroy popper instance */
  destroy: () => void;
  /** Popper instance */
  instance: ComputedRef<any>;
}

/**
 * Modal management utilities
 * @returns Modal control functions
 */
declare function useModal(): ModalReturn;

interface ModalReturn {
  /** Open modal */
  openModal: () => void;
  /** Close modal */
  closeModal: () => void;
  /** Toggle modal */
  toggleModal: () => void;
  /** Whether modal is open */
  isModalOpen: ComputedRef<boolean>;
}

/**
 * Model toggle functionality
 * @param props - Component props
 * @param emit - Component emit function
 * @returns Model toggle utilities
 */
declare function useModelToggle(
  props: ModelToggleProps,
  emit: (event: string, ...args: any[]) => void
): ModelToggleReturn;

interface ModelToggleProps {
  modelValue?: boolean;
  disabled?: boolean;
}

interface ModelToggleReturn {
  /** Whether active */
  isActive: ComputedRef<boolean>;
  /** Toggle function */
  toggle: () => void;
}

/**
 * Draggable functionality
 * @param target - Target element
 * @param options - Drag options
 * @returns Drag utilities
 */
declare function useDraggable(
  target: MaybeElementRef,
  options?: DraggableOptions
): DraggableReturn;

interface DraggableOptions {
  /** Whether initially dragging */
  initialValue?: boolean;
  /** Handle selector */
  handle?: string;
  /** Disable predicate */
  disabled?: boolean;
  /** Drag start callback */
  onStart?: (event: MouseEvent) => void;
  /** Drag move callback */
  onMove?: (event: MouseEvent) => void;
  /** Drag end callback */
  onEnd?: (event: MouseEvent) => void;
}

interface DraggableReturn {
  /** Whether dragging */
  isDragging: ComputedRef<boolean>;
  /** Position */
  position: Ref<{ x: number; y: number }>;
  /** Start dragging */
  start: (event: MouseEvent) => void;
}

/**
 * Throttled rendering for performance
 * @param callback - Render callback
 * @param delay - Throttle delay
 * @returns Throttled render function
 */
declare function useThrottleRender(
  callback: () => void,
  delay?: number
): () => void;

/**
 * Timeout management
 * @returns Timeout utilities
 */
declare function useTimeout(): TimeoutReturn;

interface TimeoutReturn {
  /** Register timeout */
  registerTimeout: (callback: () => void, delay: number) => number;
  /** Cancel timeout */
  cancelTimeout: (id: number) => void;
}

/**
 * Delayed toggle functionality
 * @param value - Toggle value
 * @param delay - Toggle delay
 * @returns Delayed toggle utilities
 */
declare function useDelayedToggle(
  value: Ref<boolean>,
  delay?: number
): DelayedToggleReturn;

interface DelayedToggleReturn {
  /** Delayed value */
  delayedValue: ComputedRef<boolean>;
  /** Cancel delay */
  cancel: () => void;
}

/**
 * Deprecation warnings for components
 * @param from - Deprecated feature
 * @param replacement - Replacement recommendation
 * @param version - Version when deprecated
 */
declare function useDeprecated(
  from: string,
  replacement: string,
  version: string
): void;

/**
 * Same target detection for events
 * @param event - Target event
 * @returns Whether same target
 */
declare function useSameTarget(event: Ref<Event | undefined>): ComputedRef<boolean>;

/**
 * Cursor position management
 * @param input - Input element reference
 * @returns Cursor utilities
 */
declare function useCursor(input: Ref<HTMLInputElement | undefined>): CursorReturn;

interface CursorReturn {
  /** Current cursor selection */
  selection: ComputedRef<{ start: number; end: number } | null>;
  /** Set cursor position */
  setCursor: (start: number, end?: number) => void;
  /** Get cursor position */
  getCursor: () => { start: number; end: number } | null;
}

type ComponentSize = '' | 'large' | 'default' | 'small';
type MaybeElementRef = HTMLElement | Ref<HTMLElement | undefined> | undefined;

interface ComputedRef<T> {
  readonly value: T;
}

interface Ref<T> {
  value: T;
}