Browser APIs

/**
 * Reactive clipboard API with permission handling
 * @param options - Configuration options
 * @returns Clipboard utilities
 */
function useClipboard(options?: UseClipboardOptions): UseClipboardReturn;

interface UseClipboardReturn {
  isSupported: ComputedRef<boolean>;
  text: ComputedRef<string>;
  copied: ComputedRef<boolean>;
  copy: (text?: string) => Promise<void>;
}

interface UseClipboardOptions extends ConfigurableNavigator {
  read?: boolean;
  source?: MaybeRefOrGetter<string>;
  copiedDuring?: number;
}

/**
 * Advanced clipboard API for multiple data types
 * @param options - Configuration options
 * @returns Advanced clipboard utilities
 */
function useClipboardItems(options?: UseClipboardItemsOptions): UseClipboardItemsReturn;

interface UseClipboardItemsReturn {
  isSupported: ComputedRef<boolean>;
  content: ComputedRef<ClipboardItems>;
  copy: (content: ClipboardItems) => Promise<void>;
}

/**
 * Reactive geolocation API with position tracking
 * @param options - Geolocation options
 * @returns Geolocation state and utilities
 */
function useGeolocation(options?: UseGeolocationOptions): UseGeolocationReturn;

interface UseGeolocationReturn {
  coords: Ref<GeolocationCoordinates>;
  locatedAt: Ref<number | null>;
  error: ShallowRef<GeolocationPositionError | null>;
  resume: Fn;
  pause: Fn;
}

interface UseGeolocationOptions extends Pausable, ConfigurableNavigator {
  enableHighAccuracy?: boolean;
  maximumAge?: number;
  timeout?: number;
  immediate?: boolean;
}

/**
 * Reactive permissions API
 * @param permissionDesc - Permission descriptor
 * @param options - Configuration options
 * @returns Permission state
 */
function usePermission(
  permissionDesc: PermissionDescriptor | PermissionDescriptor['name'],
  options?: UsePermissionOptions
): UsePermissionReturn;

interface UsePermissionReturn {
  state: Ref<PermissionState | undefined>;
  isSupported: Ref<boolean>;
  query: () => Promise<PermissionStatus | undefined>;
}

/**
 * Reactive Web Notifications API
 * @param title - Notification title
 * @param options - Configuration options
 * @returns Notification utilities
 */
function useWebNotification(
  title?: MaybeRefOrGetter<string>,
  options?: UseWebNotificationOptions
): UseWebNotificationReturn;

interface UseWebNotificationReturn {
  isSupported: ComputedRef<boolean>;
  notification: Ref<Notification | null>;
  show: (overrides?: UseWebNotificationOptions) => Promise<Notification | undefined>;
  close: () => void;
  onClick: EventHookOn<Event>;
  onShow: EventHookOn<Event>;
  onError: EventHookOn<Event>;
  onClose: EventHookOn<Event>;
}

/**
 * Programmatically open file dialog
 * @param options - File dialog options
 * @returns File dialog utilities
 */
function useFileDialog(options?: UseFileDialogOptions): UseFileDialogReturn;

interface UseFileDialogReturn {
  files: Ref<FileList | null>;
  open: (localOptions?: Partial<UseFileDialogOptions>) => void;
  reset: () => void;
  onChange: EventHookOn<Event>;
}

interface UseFileDialogOptions {
  multiple?: boolean;
  accept?: string;
  capture?: string;
  reset?: boolean;
}

/**
 * Reactive File System Access API
 * @param options - Configuration options
 * @returns File system access utilities
 */
function useFileSystemAccess(options?: UseFileSystemAccessOptions): UseFileSystemAccessReturn;

interface UseFileSystemAccessReturn {
  isSupported: ComputedRef<boolean>;
  data: Ref<string | ArrayBuffer | null>;
  file: Ref<File | null>;
  fileName: Ref<string>;
  fileMIME: Ref<string>;
  fileSize: Ref<number>;
  fileLastModified: Ref<number>;
  open: (options?: OpenFilePickerOptions) => Promise<void>;
  create: (options?: SaveFilePickerOptions) => Promise<void>;
  save: (options?: SaveFilePickerOptions) => Promise<void>;
  saveAs: (options?: SaveFilePickerOptions) => Promise<void>;
  updateData: () => Promise<void>;
}

/**
 * Reactive EyeDropper API for color picking
 * @param options - Configuration options
 * @returns EyeDropper utilities
 */
function useEyeDropper(options?: UseEyeDropperOptions): UseEyeDropperReturn;

interface UseEyeDropperReturn {
  isSupported: ComputedRef<boolean>;
  sRGBHex: Ref<string>;
  open: (openOptions?: EyeDropperOpenOptions) => Promise<{ sRGBHex: string } | undefined>;
}

/**
 * Reactive Vibration API for haptic feedback
 * @param options - Configuration options
 * @returns Vibration utilities
 */
function useVibrate(options?: UseVibrateOptions): UseVibrateReturn;

interface UseVibrateReturn {
  isSupported: ComputedRef<boolean>;
  isvibrating: Ref<boolean>;
  pattern: Ref<VibratePattern>;
  intervalControls: Pausable;
  vibrate: (pattern?: VibratePattern) => void;
  stop: () => void;
}

type VibratePattern = number | number[];

/**
 * Reactive Screen Wake Lock API
 * @param options - Configuration options
 * @returns Wake lock utilities
 */
function useWakeLock(options?: UseWakeLockOptions): UseWakeLockReturn;

interface UseWakeLockReturn {
  isSupported: ComputedRef<boolean>;
  wakeLock: Ref<WakeLockSentinel | null>;
  request: (type?: WakeLockType) => Promise<void>;
  release: () => Promise<void>;
}

/**
 * Reactive Web Share API
 * @param shareOptions - Default share options
 * @param options - Configuration options
 * @returns Share utilities
 */
function useShare(
  shareOptions?: MaybeRefOrGetter<ShareData>,
  options?: UseShareOptions
): UseShareReturn;

interface UseShareReturn {
  share: (overrideOptions?: MaybeRefOrGetter<ShareData>) => Promise<void>;
  isSupported: ComputedRef<boolean>;
}

/**
 * Reactive document title management
 * @param newTitle - New title (reactive)
 * @param options - Configuration options
 * @returns Reactive title ref
 */
function useTitle(
  newTitle?: MaybeRefOrGetter<string | null | undefined>,
  options?: UseTitleOptions
): ComputedRef<string | null | undefined>;

interface UseTitleOptions extends ConfigurableDocument {
  titleTemplate?: MaybeRefOrGetter<string> | ((title: string) => string);
  observe?: boolean;
  restoreOnUnmount?: boolean;
}

/**
 * Reactive favicon management
 * @param newIcon - New favicon URL (reactive)
 * @param options - Configuration options
 * @returns Reactive favicon ref
 */
function useFavicon(
  newIcon?: MaybeRefOrGetter<string | null | undefined>,
  options?: UseFaviconOptions
): ComputedRef<string | null | undefined>;

interface UseFaviconOptions extends ConfigurableDocument {
  baseUrl?: string;
  rel?: string;
}

/**
 * Reactive document visibility state
 * @param options - Configuration options
 * @returns Reactive visibility state
 */
function useDocumentVisibility(options?: ConfigurableDocument): Ref<DocumentVisibilityState>;

/**
 * Reactive page leave detection
 * @param options - Configuration options
 * @returns Reactive page leave state
 */
function usePageLeave(options?: ConfigurableWindow): Ref<boolean>;

/**
 * Reactive browser location information
 * @param options - Configuration options
 * @returns Reactive location state
 */
function useBrowserLocation(options?: UseBrowserLocationOptions): UseBrowserLocationReturn;

interface UseBrowserLocationReturn {
  trigger: () => void;
  coords: Ref<GeolocationCoordinates>;
  locatedAt: Ref<number | null>;
  error: ShallowRef<GeolocationPositionError | null>;
  resume: Fn;
  pause: Fn;
}

/**
 * Reactive navigator language
 * @param options - Configuration options
 * @returns Reactive language state
 */
function useNavigatorLanguage(options?: ConfigurableNavigator): UseNavigatorLanguageReturn;

interface UseNavigatorLanguageReturn {
  isSupported: Ref<boolean>;
  language: ComputedRef<string>;
  languages: ComputedRef<readonly string[]>;
}

/**
 * Reactive color mode with automatic persistence
 * @param options - Color mode configuration options
 * @returns Reactive color mode state
 */
function useColorMode<T extends string = BasicColorMode>(
  options?: UseColorModeOptions<T>
): Ref<T | BasicColorMode>;

interface UseColorModeOptions<T extends string = BasicColorMode> {
  selector?: string | MaybeElementRef;
  attribute?: string;
  initialValue?: MaybeRefOrGetter<T | BasicColorSchema>;
  modes?: Partial<Record<T | BasicColorSchema, string>>;
  onChanged?: (mode: T | BasicColorMode, defaultHandler: (mode: T | BasicColorMode) => void) => void;
  storageKey?: string;
  storage?: StorageLike;
  storageRef?: Ref<T | BasicColorMode>;
  emitAuto?: boolean;
  disableTransition?: boolean;
}

type BasicColorMode = 'light' | 'dark';
type BasicColorSchema = BasicColorMode | 'auto';

/**
 * Reactive dark mode with auto data persistence
 * @param options - Dark mode configuration options
 * @returns Reactive dark mode state
 */
function useDark(options?: UseDarkOptions): WritableComputedRef<boolean>;

interface UseDarkOptions extends Omit<UseColorModeOptions<BasicColorSchema>, 'modes' | 'onChanged'> {
  valueDark?: string;
  valueLight?: string;
  onChanged?: (isDark: boolean, defaultHandler: (mode: BasicColorSchema) => void, mode: BasicColorSchema) => void;
}

/**
 * Reactive fullscreen API
 * @param target - Target element for fullscreen
 * @param options - Fullscreen configuration options
 * @returns Fullscreen state and controls
 */
function useFullscreen(
  target?: MaybeElementRef,
  options?: UseFullscreenOptions
): UseFullscreenReturn;

interface UseFullscreenReturn {
  isSupported: ComputedRef<boolean>;
  isFullscreen: Ref<boolean>;
  enter: () => Promise<void>;
  exit: () => Promise<void>;
  toggle: () => Promise<void>;
}

interface UseFullscreenOptions extends ConfigurableDocument {
  autoExit?: boolean;
}

/**
 * Reactive user media access
 * @param options - Media constraints and configuration
 * @returns Media stream state and controls
 */
function useUserMedia(
  options?: UseUserMediaOptions
): UseUserMediaReturn;

interface UseUserMediaReturn {
  isSupported: ComputedRef<boolean>;
  stream: Ref<MediaStream | undefined>;
  start: () => Promise<MediaStream | undefined>;
  stop: () => void;
  restart: () => Promise<MediaStream | undefined>;
  videoInputs: ComputedRef<MediaDeviceInfo[]>;
  audioInputs: ComputedRef<MediaDeviceInfo[]>;
  audioOutputs: ComputedRef<MediaDeviceInfo[]>;
}

interface UseUserMediaOptions extends ConfigurableNavigator {
  enabled?: MaybeRef<boolean>;
  autoSwitch?: MaybeRef<boolean>;
  constraints?: MaybeRef<MediaStreamConstraints>;
}

/**
 * Reactive screen sharing access
 * @param options - Display media configuration options
 * @returns Display media stream state and controls
 */
function useDisplayMedia(
  options?: UseDisplayMediaOptions
): UseDisplayMediaReturn;

interface UseDisplayMediaReturn {
  isSupported: ComputedRef<boolean>;
  stream: Ref<MediaStream | undefined>;
  start: () => Promise<MediaStream | undefined>;
  stop: () => void;
}

interface UseDisplayMediaOptions {
  enabled?: MaybeRef<boolean>;
  video?: boolean | MediaTrackConstraints;
  audio?: boolean | MediaTrackConstraints;
}