Feature Request: Configurable Browser Globals

[huntabyte]

Describe the feature in detail (code, mocks, or screenshots encouraged)

Add the ability to configure custom window, document, navigator, and location objects for utilities that currently rely on global objects. This would make the library more flexible for testing environments, iframes, and other non-standard contexts.

Current Problem

Currently, utilities in the library directly reference global objects like window and document, creating a few challenges:

• Testing becomes difficult as we can't easily mock global objects
• Working with iframes requires awkward workarounds
• Shadow DOM scenarios (surprisingly Shadow DOM support requests have been on the rise in all libraries I maintain)

Proposed API

This is how it's handled in VueUse, and it makes a lot of sense. Anywhere we use a global, we provide an optional config where the user can provide their own.

// configurable-globals.ts
import { BROWSER } from 'esm-env';

export type ConfigurableWindow = {
  window?: Window
}

export type ConfigurableDocument = {
  document?: Document
}

export type ConfigurableNavigator =  {
  navigator?: Navigator
}

export type ConfigurableLocation = {
  location?: Location
}

// Default values
export const defaultWindow = /* #__PURE__ */ BROWSER ? window : undefined
export const defaultDocument = /* #__PURE__ */ BROWSER ? window.document : undefined
export const defaultNavigator = /* #__PURE__ */ BROWSER ? window.navigator : undefined
export const defaultLocation = /* #__PURE__ */ BROWSER ? window.location : undefined

What type of pull request would this be?

None

Provide relevant links or additional information.

No response