@entry-ui/utilities 0.6.0 → 0.8.0

package/dist/chunk-ATOIAGQE.js

@@ -0,0 +1,2 @@
+import {a as a$2}from'./chunk-WWLZE6DE.js';import {a as a$1}from'./chunk-QVG7VOJQ.js';import {a}from'./chunk-EQONVDWV.js';var i=m=>{let{element:e,focusVisible:c=false,preventScroll:l=false,select:r=false}=m;if("focus"in e){let f=a(e),n=a$1(f);e.focus({focusVisible:c,preventScroll:l}),e!==n&&a$2(e)&&r&&e.select();}};export{i as a};//# sourceMappingURL=chunk-ATOIAGQE.js.map
+//# sourceMappingURL=chunk-ATOIAGQE.js.map

package/dist/chunk-ATOIAGQE.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/focus-element/focus-element.ts"],"names":["focusElement","params","element","focusVisible","preventScroll","select","doc","getDocument","previouslyFocusedElement","getActiveElement","isSelectableInput"],"mappings":"0HA+BO,IAAMA,CAAAA,CAAgBC,GAA+B,CAC1D,GAAM,CAAE,OAAA,CAAAC,CAAAA,CAAS,YAAA,CAAAC,CAAAA,CAAe,KAAA,CAAO,aAAA,CAAAC,EAAgB,KAAA,CAAO,MAAA,CAAAC,EAAS,KAAM,CAAA,CAAIJ,EAGjF,GAAI,OAAA,GAAWC,CAAAA,CAAS,CACtB,IAAMI,CAAAA,CAAMC,EAAYL,CAAO,CAAA,CACzBM,EAA2BC,GAAAA,CAAiBH,CAAG,EAKrDJ,CAAAA,CAAQ,KAAA,CAAM,CAAE,YAAA,CAAAC,CAAAA,CAAc,aAAA,CAAAC,CAAc,CAAC,CAAA,CAKzCF,CAAAA,GAAYM,CAAAA,EAA4BE,GAAAA,CAAkBR,CAAO,GAAKG,CAAAA,EACxEH,CAAAA,CAAQ,MAAA,GAEZ,CACF","file":"chunk-ATOIAGQE.js","sourcesContent":["import type { FocusElementParams } from './focus-element.types';\nimport { getDocument } from '../get-document';\nimport { getActiveElement } from '../get-active-element';\nimport { isSelectableInput } from '../is-selectable-input';\n\n/**\n * Programmatically manages focus for a given DOM element with extended configuration.\n *\n * This utility wraps the native `HTMLElement.focus()` method, providing a unified\n * interface for common focus-related tasks such as controlling the focus ring\n * visibility, preventing automatic scrolling, and selecting input text.\n *\n * It includes a safety check to ensure the target element is focusable and\n * optimizes the user experience by avoiding redundant selection operations\n * if the element is already active.\n *\n * @example\n * ```ts\n * // Basic focus with scroll prevention\n * focusElement({ element: myButton, preventScroll: true });\n *\n * // Focus an input and automatically select its text content\n * focusElement({ element: myInput, select: true });\n *\n * // Requesting selection on an already active element will focus it without re-selecting\n * focusElement({ element: alreadyActiveInput, select: true });\n *\n * // Triggering focus with a visible focus ring (mimics keyboard navigation)\n * focusElement({ element: myLink, focusVisible: true });\n * ```\n */\nexport const focusElement = (params: FocusElementParams) => {\n  const { element, focusVisible = false, preventScroll = false, select = false } = params;\n\n  // Only focus if that element is focusable.\n  if ('focus' in element) {\n    const doc = getDocument(element);\n    const previouslyFocusedElement = getActiveElement(doc);\n\n    // @ts-expect-error - `focusVisible` is an experimental option not yet in TS types\n    // Browsers that do not support the `focusVisible` option will simply\n    // ignore it and perform a standard focus without throwing an error.\n    element.focus({ focusVisible, preventScroll });\n\n    // If the element is an input field and selection is explicitly requested,\n    // select its content only if it wasn't the previously focused element.\n    // This avoids redundant operations and enhances the user experience.\n    if (element !== previouslyFocusedElement && isSelectableInput(element) && select) {\n      element.select();\n    }\n  }\n};\n"]}

package/dist/chunk-AYPZYNVX.js

@@ -0,0 +1,2 @@
+var o=a=>{let{value:m,min:p,max:t}=a;return Math.min(t,Math.max(p,m))};export{o as a};//# sourceMappingURL=chunk-AYPZYNVX.js.map
+//# sourceMappingURL=chunk-AYPZYNVX.js.map

package/dist/chunk-AYPZYNVX.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/clamp/clamp.ts"],"names":["clamp","params","value","min","max"],"mappings":"AAqBO,IAAMA,CAAAA,CAASC,GAAwB,CAC5C,GAAM,CAAE,KAAA,CAAAC,CAAAA,CAAO,GAAA,CAAAC,CAAAA,CAAK,GAAA,CAAAC,CAAI,EAAIH,CAAAA,CAE5B,OAAO,KAAK,GAAA,CAAIG,CAAAA,CAAK,KAAK,GAAA,CAAID,CAAAA,CAAKD,CAAK,CAAC,CAC3C","file":"chunk-AYPZYNVX.js","sourcesContent":["import type { ClampParams } from './clamp.types';\n\n/**\n * Clamps a number between a minimum and maximum value.\n *\n * This utility ensures that the returned value is restricted to a specified range.\n * If the input value is smaller than the minimum boundary, the minimum value is\n * returned. If it exceeds the maximum boundary, the maximum value is returned.\n *\n * @example\n * ```ts\n * clamp({ value: 150, min: 0, max: 100 });\n * // Returns: 100\n *\n * clamp({ value: -20, min: 0, max: 100 });\n * // Returns: 0\n *\n * clamp({ value: 50, min: 0, max: 100 });\n * // Returns: 50\n * ```\n */\nexport const clamp = (params: ClampParams) => {\n  const { value, min, max } = params;\n\n  return Math.min(max, Math.max(min, value));\n};\n"]}

package/dist/chunk-EQONVDWV.js

@@ -0,0 +1,2 @@
+var n=e=>e?.ownerDocument||document;export{n as a};//# sourceMappingURL=chunk-EQONVDWV.js.map
+//# sourceMappingURL=chunk-EQONVDWV.js.map

package/dist/chunk-EQONVDWV.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/get-document/get-document.ts"],"names":["getDocument","node"],"mappings":"AAmBO,IAAMA,CAAAA,CAAeC,CAAAA,EACnBA,CAAAA,EAAM,aAAA,EAAiB","file":"chunk-EQONVDWV.js","sourcesContent":["/**\n * Retrieves the document object associated with a given DOM node, ensuring the correct execution context.\n *\n * This utility identifies the correct owner document for a specific node. It is\n * particularly useful when working with applications that utilize iframes or\n * multiple windows, as it ensures that document-level APIs (like `createElement`,\n * `getElementById`, or `addEventListener`) are accessed from the node's actual\n * environment rather than the current global document.\n *\n * @example\n * ```ts\n * getDocument(document.getElementById(\"my-element\"));\n * // Returns: the document object where the element resides\n *\n * getDocument(null);\n * // Returns: the global document object as a fallback\n * ```\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport const getDocument = (node: any): Document => {\n  return node?.ownerDocument || document;\n};\n"]}

package/dist/chunk-IUHRHZ62.js

@@ -0,0 +1,2 @@
+var o=a=>{let{array:r,startIndex:p}=a;return r.map((m,t)=>r[(p+t)%r.length])};export{o as a};//# sourceMappingURL=chunk-IUHRHZ62.js.map
+//# sourceMappingURL=chunk-IUHRHZ62.js.map

package/dist/chunk-IUHRHZ62.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/wrap-array/wrap-array.ts"],"names":["wrapArray","params","array","startIndex","_","index"],"mappings":"AAsBO,IAAMA,CAAAA,CAAgBC,GAA+B,CAC1D,GAAM,CAAE,KAAA,CAAAC,CAAAA,CAAO,UAAA,CAAAC,CAAW,CAAA,CAAIF,CAAAA,CAE9B,OAAOC,CAAAA,CAAM,GAAA,CAAO,CAACE,CAAAA,CAAGC,CAAAA,GAAUH,CAAAA,CAAAA,CAAOC,EAAaE,CAAAA,EAASH,CAAAA,CAAM,MAAM,CAAE,CAC/E","file":"chunk-IUHRHZ62.js","sourcesContent":["import type { WrapArrayParams } from './wrap-array.types';\n\n/**\n * Rearranges an array by shifting its starting point to a specified index.\n *\n * This utility creates a circular shift of the array elements. The element at\n * `startIndex` becomes the first element of the resulting array, followed by\n * subsequent elements. When the end of the original array is reached, it wraps\n * around to the beginning until all elements are included.\n *\n * @example\n * ```ts\n * wrapArray({ array: [\"a\", \"b\", \"c\", \"d\"], startIndex: 2 });\n * // Returns: [\"c\", \"d\", \"a\", \"b\"]\n *\n * wrapArray({ array: [\"a\", \"b\", \"c\", \"d\"], startIndex: 3 });\n * // Returns: [\"d\", \"a\", \"b\", \"c\"]\n *\n * wrapArray({ array: [\"a\", \"b\", \"c\", \"d\"], startIndex: 0 });\n * // Returns: [\"a\", \"b\", \"c\", \"d\"]\n * ```\n */\nexport const wrapArray = <T>(params: WrapArrayParams<T>) => {\n  const { array, startIndex } = params;\n\n  return array.map<T>((_, index) => array[(startIndex + index) % array.length]!);\n};\n"]}

package/dist/chunk-P7NW64IN.js

@@ -0,0 +1,2 @@
+var n=async a=>{let{value:p,onSuccess:e,onError:r}=a,t=document.defaultView||window;try{if(!t.navigator.clipboard?.writeText){r?.({type:"NOT_SUPPORTED"});return}await t.navigator.clipboard.writeText(p),e?.();}catch(o){let i=o instanceof Error?o.message:String(o);r?.({type:"COPY_FAILED",message:i});}};export{n as a};//# sourceMappingURL=chunk-P7NW64IN.js.map
+//# sourceMappingURL=chunk-P7NW64IN.js.map

package/dist/chunk-P7NW64IN.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/copy-to-clipboard/copy-to-clipboard.ts"],"names":["copyToClipboard","params","value","onSuccess","onError","win","error","message"],"mappings":"AAqBO,IAAMA,CAAAA,CAAkB,MAAOC,CAAAA,EAAkC,CACtE,GAAM,CAAE,KAAA,CAAAC,CAAAA,CAAO,SAAA,CAAAC,CAAAA,CAAW,OAAA,CAAAC,CAAQ,EAAIH,CAAAA,CAEhCI,CAAAA,CAAM,QAAA,CAAS,WAAA,EAAe,MAAA,CAEpC,GAAI,CACF,GAAI,CAACA,CAAAA,CAAI,SAAA,CAAU,SAAA,EAAW,SAAA,CAAW,CACvCD,CAAAA,GAAU,CAAE,KAAM,eAAgB,CAAC,CAAA,CACnC,MACF,CAEA,MAAMC,CAAAA,CAAI,SAAA,CAAU,SAAA,CAAU,SAAA,CAAUH,CAAK,CAAA,CAC7CC,CAAAA,KACF,CAAA,MAASG,CAAAA,CAAO,CACd,IAAMC,CAAAA,CAAUD,CAAAA,YAAiB,KAAA,CAAQA,CAAAA,CAAM,OAAA,CAAU,MAAA,CAAOA,CAAK,CAAA,CACrEF,CAAAA,GAAU,CAAE,IAAA,CAAM,aAAA,CAAe,OAAA,CAAAG,CAAQ,CAAC,EAC5C,CACF","file":"chunk-P7NW64IN.js","sourcesContent":["import type { CopyToClipboardParams } from './copy-to-clipboard.types';\n\n/**\n * Asynchronously transfers text to the system clipboard using the Clipboard API.\n *\n * This utility provides a structured wrapper around `navigator.clipboard.writeText`,\n * offering specific error types to distinguish between unsupported environments\n * and runtime failures.\n *\n * This function expects a browser environment where `window` or\n * `document` is globally available.\n *\n * @example\n * ```ts\n * copyToClipboard({\n * \tvalue: \"Hello World\",\n * \tonSuccess: () => console.log(\"Text copied!\"),\n * \tonError: (err) => console.error(`Copy failed: ${err.type}, ${err.message}`),\n * });\n * ```\n */\nexport const copyToClipboard = async (params: CopyToClipboardParams) => {\n  const { value, onSuccess, onError } = params;\n\n  const win = document.defaultView || window;\n\n  try {\n    if (!win.navigator.clipboard?.writeText) {\n      onError?.({ type: 'NOT_SUPPORTED' });\n      return;\n    }\n\n    await win.navigator.clipboard.writeText(value);\n    onSuccess?.();\n  } catch (error) {\n    const message = error instanceof Error ? error.message : String(error);\n    onError?.({ type: 'COPY_FAILED', message });\n  }\n};\n"]}

package/dist/chunk-QVG7VOJQ.js

@@ -0,0 +1,2 @@
+var n=t=>{let e=t.activeElement;for(;e?.shadowRoot?.activeElement!=null;)e=e.shadowRoot.activeElement;return e};export{n as a};//# sourceMappingURL=chunk-QVG7VOJQ.js.map
+//# sourceMappingURL=chunk-QVG7VOJQ.js.map

package/dist/chunk-QVG7VOJQ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/get-active-element/get-active-element.ts"],"names":["getActiveElement","doc","activeElement"],"mappings":"AAkBO,IAAMA,EAAoBC,CAAAA,EAAkB,CACjD,IAAIC,CAAAA,CAAgBD,EAAI,aAAA,CAExB,KAAOC,CAAAA,EAAe,UAAA,EAAY,eAAiB,IAAA,EACjDA,CAAAA,CAAgBA,EAAc,UAAA,CAAW,aAAA,CAG3C,OAAOA,CACT","file":"chunk-QVG7VOJQ.js","sourcesContent":["/**\n * Recursively retrieves the currently focused element, including those nested within Shadow DOM.\n *\n * Unlike the standard `document.activeElement`, which only returns the host element\n * of a Shadow Root, this utility traverses through any available `shadowRoot` to\n * pinpoint the actual element that holds focus deep within the DOM tree.\n *\n * @example\n * ```ts\n * // If focus is inside a web component's shadow DOM:\n * getActiveElement(document);\n * // Returns: <input /> (inside shadow root)\n *\n * // Standard approach would only return:\n * document.activeElement;\n * // Returns: <my-custom-component /> (the host)\n * ```\n */\nexport const getActiveElement = (doc: Document) => {\n  let activeElement = doc.activeElement;\n\n  while (activeElement?.shadowRoot?.activeElement != null) {\n    activeElement = activeElement.shadowRoot.activeElement;\n  }\n\n  return activeElement;\n};\n"]}

package/dist/{chunk-RZEIOZGJ.js → chunk-R2W6HH4I.js}

@@ -1,2 +1,2 @@
-import {a}from'./chunk-TJWADQ7V.js';var r=t=>{let e=t.cloneNode(true);e.setAttribute("aria-hidden","true"),Object.assign(e.style,{pointerEvents:"none",userSelect:"none",overflow:"visible",height:"auto",maxHeight:"none",opacity:"0",visibility:"hidden",display:"block",contentVisibility:"visible",transition:"none",animation:"none",position:"absolute",top:"-9999px"}),t.after(e);let{height:n}=a(e);return e.remove(),n};export{r as a};//# sourceMappingURL=chunk-RZEIOZGJ.js.map
-//# sourceMappingURL=chunk-RZEIOZGJ.js.map
+import {a}from'./chunk-X7ZJXXGU.js';var r=t=>{let e=t.cloneNode(true);e.setAttribute("aria-hidden","true"),Object.assign(e.style,{pointerEvents:"none",userSelect:"none",overflow:"visible",height:"auto",maxHeight:"none",opacity:"0",visibility:"hidden",display:"block",contentVisibility:"visible",transition:"none",animation:"none",position:"absolute",top:"-9999px"}),t.after(e);let{height:n}=a(e);return e.remove(),n};export{r as a};//# sourceMappingURL=chunk-R2W6HH4I.js.map
+//# sourceMappingURL=chunk-R2W6HH4I.js.map

package/dist/{chunk-RZEIOZGJ.js.map → chunk-R2W6HH4I.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/get-hidden-element-height/get-hidden-element-height.ts"],"names":["getHiddenElementHeight","element","cloneElement","height","getCssDimensions"],"mappings":"oCAsBO,IAAMA,CAAAA,CAA0BC,CAAAA,EAAyB,CAC9D,IAAMC,CAAAA,CAAeD,CAAAA,CAAQ,SAAA,CAAU,IAAI,CAAA,CAE3CC,CAAAA,CAAa,YAAA,CAAa,aAAA,CAAe,MAAM,CAAA,CAE/C,MAAA,CAAO,MAAA,CAAOA,CAAAA,CAAa,KAAA,CAAO,CAChC,aAAA,CAAe,MAAA,CACf,UAAA,CAAY,MAAA,CACZ,QAAA,CAAU,SAAA,CACV,MAAA,CAAQ,MAAA,CACR,SAAA,CAAW,OACX,OAAA,CAAS,GAAA,CACT,UAAA,CAAY,QAAA,CACZ,OAAA,CAAS,OAAA,CACT,iBAAA,CAAmB,SAAA,CACnB,UAAA,CAAY,MAAA,CACZ,SAAA,CAAW,MAAA,CACX,QAAA,CAAU,UAAA,CACV,GAAA,CAAK,SACP,CAAC,CAAA,CAEDD,CAAAA,CAAQ,KAAA,CAAMC,CAAY,CAAA,CAE1B,GAAM,CAAE,MAAA,CAAAC,CAAO,CAAA,CAAIC,CAAAA,CAAiBF,CAAY,CAAA,CAEhD,OAAAA,CAAAA,CAAa,MAAA,GAENC,CACT","file":"chunk-RZEIOZGJ.js","sourcesContent":["import { getCssDimensions } from '../get-css-dimensions';\n\n/**\n * Calculates the natural height of an element that is otherwise hidden from the layout.\n *\n * This function handles cases where an element's dimensions cannot be accurately measured\n * (e.g., when it is set to `display: none` and occupies no space in the document). It\n * works by creating an invisible, deep clone of the element and temporarily injecting\n * it into the DOM at a position far outside the visible viewport.\n *\n * The clone is styled to be non-interactive and layout-neutral by overriding its display,\n * positioning, and visibility properties. This ensures that its presence does not\n * interfere with the user experience, trigger unintended layout shifts, or affect\n * accessibility trees. Once the height is captured, the clone is immediately removed\n * from the document to maintain DOM cleanliness.\n *\n * @example\n * ```ts\n * getHiddenElementHeight(myHiddenElement);\n * // Returns: 42\n * ```\n */\nexport const getHiddenElementHeight = (element: HTMLElement) => {\n  const cloneElement = element.cloneNode(true) as HTMLElement;\n\n  cloneElement.setAttribute('aria-hidden', 'true');\n\n  Object.assign(cloneElement.style, {\n    pointerEvents: 'none',\n    userSelect: 'none',\n    overflow: 'visible',\n    height: 'auto',\n    maxHeight: 'none',\n    opacity: '0',\n    visibility: 'hidden',\n    display: 'block',\n    contentVisibility: 'visible',\n    transition: 'none',\n    animation: 'none',\n    position: 'absolute',\n    top: '-9999px',\n  });\n\n  element.after(cloneElement);\n\n  const { height } = getCssDimensions(cloneElement);\n\n  cloneElement.remove();\n\n  return height;\n};\n"]}
+{"version":3,"sources":["../src/get-hidden-element-height/get-hidden-element-height.ts"],"names":["getHiddenElementHeight","element","cloneElement","height","getCssDimensions"],"mappings":"oCAsBO,IAAMA,CAAAA,CAA0BC,CAAAA,EAAyB,CAC9D,IAAMC,CAAAA,CAAeD,CAAAA,CAAQ,SAAA,CAAU,IAAI,CAAA,CAE3CC,CAAAA,CAAa,YAAA,CAAa,aAAA,CAAe,MAAM,CAAA,CAE/C,MAAA,CAAO,MAAA,CAAOA,CAAAA,CAAa,KAAA,CAAO,CAChC,aAAA,CAAe,MAAA,CACf,UAAA,CAAY,MAAA,CACZ,QAAA,CAAU,SAAA,CACV,MAAA,CAAQ,MAAA,CACR,SAAA,CAAW,OACX,OAAA,CAAS,GAAA,CACT,UAAA,CAAY,QAAA,CACZ,OAAA,CAAS,OAAA,CACT,iBAAA,CAAmB,SAAA,CACnB,UAAA,CAAY,MAAA,CACZ,SAAA,CAAW,MAAA,CACX,QAAA,CAAU,UAAA,CACV,GAAA,CAAK,SACP,CAAC,CAAA,CAEDD,CAAAA,CAAQ,KAAA,CAAMC,CAAY,CAAA,CAE1B,GAAM,CAAE,MAAA,CAAAC,CAAO,CAAA,CAAIC,CAAAA,CAAiBF,CAAY,CAAA,CAEhD,OAAAA,CAAAA,CAAa,MAAA,GAENC,CACT","file":"chunk-R2W6HH4I.js","sourcesContent":["import { getCssDimensions } from '../get-css-dimensions';\n\n/**\n * Calculates the natural height of an element that is otherwise hidden from the layout.\n *\n * This function handles cases where an element's dimensions cannot be accurately measured\n * (e.g., when it is set to `display: none` and occupies no space in the document). It\n * works by creating an invisible, deep clone of the element and temporarily injecting\n * it into the DOM at a position far outside the visible viewport.\n *\n * The clone is styled to be non-interactive and layout-neutral by overriding its display,\n * positioning, and visibility properties. This ensures that its presence does not\n * interfere with the user experience, trigger unintended layout shifts, or affect\n * accessibility trees. Once the height is captured, the clone is immediately removed\n * from the document to maintain DOM cleanliness.\n *\n * @example\n * ```ts\n * getHiddenElementHeight(myHiddenElement);\n * // Returns: 42\n * ```\n */\nexport const getHiddenElementHeight = (element: HTMLElement) => {\n  const cloneElement = element.cloneNode(true) as HTMLElement;\n\n  cloneElement.setAttribute('aria-hidden', 'true');\n\n  Object.assign(cloneElement.style, {\n    pointerEvents: 'none',\n    userSelect: 'none',\n    overflow: 'visible',\n    height: 'auto',\n    maxHeight: 'none',\n    opacity: '0',\n    visibility: 'hidden',\n    display: 'block',\n    contentVisibility: 'visible',\n    transition: 'none',\n    animation: 'none',\n    position: 'absolute',\n    top: '-9999px',\n  });\n\n  element.after(cloneElement);\n\n  const { height } = getCssDimensions(cloneElement);\n\n  cloneElement.remove();\n\n  return height;\n};\n"]}

package/dist/chunk-RTJWUKV6.js

@@ -0,0 +1,2 @@
+import {a as a$1}from'./chunk-H2U5U7XY.js';import {a}from'./chunk-V3434ODU.js';var i=e=>a()?e instanceof HTMLElement||e instanceof a$1(e).HTMLElement:false;export{i as a};//# sourceMappingURL=chunk-RTJWUKV6.js.map
+//# sourceMappingURL=chunk-RTJWUKV6.js.map

package/dist/{chunk-KSDRQLOI.js.map → chunk-RTJWUKV6.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/is-html-element/is-html-element.ts"],"names":["isHTMLElement","value","hasWindow","getWindow"],"mappings":"+EAyBO,IAAMA,CAAAA,CAAiBC,CAAAA,EACvBC,CAAAA,EAAU,CAIRD,CAAAA,YAAiB,aAAeA,CAAAA,YAAiBE,GAAAA,CAAUF,CAAK,CAAA,CAAE,WAAA,CAHhE","file":"chunk-KSDRQLOI.js","sourcesContent":["import { hasWindow } from '../has-window';\nimport { getWindow } from '../get-window';\n\n/**\n * Verifies whether a given value is an instance of `HTMLElement`, with support for cross-realm environments.\n *\n * This utility provides a cross-realm safe check to determine if a value is a\n * standard HTML element. It first ensures a window environment is available\n * and then checks the instance against both the current global `HTMLElement`\n * and the `HTMLElement` constructor from the node's specific window context.\n * This prevents false negatives when elements are passed between different\n * frames or windows.\n *\n * @example\n * ```ts\n * isHTMLElement(document.createElement('div'));\n * // Returns: true\n *\n * isHTMLElement(null);\n * // Returns: false\n *\n * isHTMLElement(iframeElement.contentDocument.body);\n * // Returns: true (even if the instance comes from another window context)\n * ```\n */\nexport const isHTMLElement = (value: unknown): value is HTMLElement => {\n  if (!hasWindow()) {\n    return false;\n  }\n\n  return value instanceof HTMLElement || value instanceof getWindow(value).HTMLElement;\n};\n"]}
+{"version":3,"sources":["../src/is-html-element/is-html-element.ts"],"names":["isHTMLElement","value","hasWindow","getWindow"],"mappings":"+EAyBO,IAAMA,CAAAA,CAAiBC,CAAAA,EACvBC,CAAAA,EAAU,CAIRD,CAAAA,YAAiB,aAAeA,CAAAA,YAAiBE,GAAAA,CAAUF,CAAK,CAAA,CAAE,WAAA,CAHhE","file":"chunk-RTJWUKV6.js","sourcesContent":["import { hasWindow } from '../has-window';\nimport { getWindow } from '../get-window';\n\n/**\n * Verifies whether a given value is an instance of `HTMLElement`, with support for cross-realm environments.\n *\n * This utility provides a cross-realm safe check to determine if a value is a\n * standard HTML element. It first ensures a window environment is available\n * and then checks the instance against both the current global `HTMLElement`\n * and the `HTMLElement` constructor from the node's specific window context.\n * This prevents false negatives when elements are passed between different\n * frames or windows.\n *\n * @example\n * ```ts\n * isHTMLElement(document.createElement('div'));\n * // Returns: true\n *\n * isHTMLElement(null);\n * // Returns: false\n *\n * isHTMLElement(iframeElement.contentDocument.body);\n * // Returns: true (even if the instance comes from another window context)\n * ```\n */\nexport const isHTMLElement = (value: unknown): value is HTMLElement => {\n  if (!hasWindow()) {\n    return false;\n  }\n\n  return value instanceof HTMLElement || value instanceof getWindow(value).HTMLElement;\n};\n"]}

package/dist/chunk-TOBJAPHB.js

@@ -0,0 +1,2 @@
+import {a as a$2}from'./chunk-ATOIAGQE.js';import {a as a$1}from'./chunk-QVG7VOJQ.js';import {a}from'./chunk-EQONVDWV.js';var p=n=>{let{candidates:t,focusVisible:f=false,preventScroll:i=false,select:l=false}=n,o=a(t[0]),s=a$1(o);for(let r of t)if(r===s||(a$2({element:r,focusVisible:f,preventScroll:i,select:l}),a$1(o)!==s))return};export{p as a};//# sourceMappingURL=chunk-TOBJAPHB.js.map
+//# sourceMappingURL=chunk-TOBJAPHB.js.map

package/dist/chunk-TOBJAPHB.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/focus-first-element/focus-first-element.ts"],"names":["focusFirstElement","params","candidates","focusVisible","preventScroll","select","doc","getDocument","previouslyFocusedElement","getActiveElement","candidate","focusElement"],"mappings":"0HAuBO,IAAMA,CAAAA,CAAqBC,GAAoC,CACpE,GAAM,CAAE,UAAA,CAAAC,CAAAA,CAAY,YAAA,CAAAC,CAAAA,CAAe,KAAA,CAAO,aAAA,CAAAC,EAAgB,KAAA,CAAO,MAAA,CAAAC,CAAAA,CAAS,KAAM,CAAA,CAAIJ,CAAAA,CAE9EK,EAAMC,CAAAA,CAAYL,CAAAA,CAAW,CAAC,CAAC,CAAA,CAC/BM,CAAAA,CAA2BC,IAAiBH,CAAG,CAAA,CAErD,QAAWI,CAAAA,IAAaR,CAAAA,CAKtB,GAJIQ,CAAAA,GAAcF,CAAAA,GAElBG,GAAAA,CAAa,CAAE,OAAA,CAASD,CAAAA,CAAW,aAAAP,CAAAA,CAAc,aAAA,CAAAC,CAAAA,CAAe,MAAA,CAAAC,CAAO,CAAC,EAEpEI,GAAAA,CAAiBH,CAAG,CAAA,GAAME,CAAAA,CAAAA,CAA0B,MAE5D","file":"chunk-TOBJAPHB.js","sourcesContent":["import type { FocusFirstElementParams } from './focus-first-element.types';\nimport { getDocument } from '../get-document';\nimport { getActiveElement } from '../get-active-element';\nimport { focusElement } from '../focus-element';\n\n/**\n * Attempts to focus the first available element from a list of candidates.\n *\n * This function iterates through an array of elements and tries to set focus on each\n * one sequentially. The process stops as soon as an element successfully receives focus\n * (i.e., when the document's active element changes). This is particularly useful for\n * managing focus in modals, forms, or complex components where the primary focus target\n * might be conditional or dynamic.\n *\n * @example\n * ```ts\n * // Focus the first visible input or fallback to a close button\n * focusFirstElement({ candidates: [input, closeButton], select: true });\n *\n * // Attempt to focus multiple elements, preventing scroll on the successful one\n * focusFirstElement({ candidates: [primaryAction, secondaryAction], preventScroll: true });\n * ```\n */\nexport const focusFirstElement = (params: FocusFirstElementParams) => {\n  const { candidates, focusVisible = false, preventScroll = false, select = false } = params;\n\n  const doc = getDocument(candidates[0]);\n  const previouslyFocusedElement = getActiveElement(doc);\n\n  for (const candidate of candidates) {\n    if (candidate === previouslyFocusedElement) return;\n\n    focusElement({ element: candidate, focusVisible, preventScroll, select });\n\n    if (getActiveElement(doc) !== previouslyFocusedElement) return;\n  }\n};\n"]}

package/dist/chunk-WWLZE6DE.js

@@ -0,0 +1,2 @@
+var l=e=>e instanceof HTMLInputElement&&"select"in e;export{l as a};//# sourceMappingURL=chunk-WWLZE6DE.js.map
+//# sourceMappingURL=chunk-WWLZE6DE.js.map

package/dist/chunk-WWLZE6DE.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/is-selectable-input/is-selectable-input.ts"],"names":["isSelectableInput","element"],"mappings":"AAiBO,IAAMA,CAAAA,CAAqBC,CAAAA,EACzBA,CAAAA,YAAmB,gBAAA,EAAoB,QAAA,GAAYA","file":"chunk-WWLZE6DE.js","sourcesContent":["/**\n * Determines whether a given HTML element is an input that supports text selection.\n *\n * This utility performs a type guard check to verify if the element is an instance\n * of `HTMLInputElement` and explicitly contains the `select` method. This is\n * particularly useful before calling `element.select()` to avoid runtime errors\n * on input types that do not support selection (e.g., `type=\"date\"` in some browsers).\n *\n * @example\n * ```ts\n * const input = document.querySelector('input[type=\"text\"]');\n *\n * if (isSelectableInput(input)) {\n * \tinput.select();\n * }\n * ```\n */\nexport const isSelectableInput = (element: HTMLElement) => {\n  return element instanceof HTMLInputElement && 'select' in element;\n};\n"]}

package/dist/{chunk-TJWADQ7V.js → chunk-X7ZJXXGU.js}

@@ -1,2 +1,2 @@
-import {a as a$1}from'./chunk-KSDRQLOI.js';import {a}from'./chunk-5BI2X7JA.js';var l=s=>{let o=a(s),t=parseFloat(o.width)||0,e=parseFloat(o.height)||0,i=a$1(s),n=i?s.offsetWidth:t,r=i?s.offsetHeight:e;return (Math.round(t)!==n||Math.round(e)!==r)&&(t=n,e=r),{width:t,height:e}};export{l as a};//# sourceMappingURL=chunk-TJWADQ7V.js.map
-//# sourceMappingURL=chunk-TJWADQ7V.js.map
+import {a}from'./chunk-5BI2X7JA.js';import {a as a$1}from'./chunk-RTJWUKV6.js';var l=s=>{let o=a(s),t=parseFloat(o.width)||0,e=parseFloat(o.height)||0,i=a$1(s),n=i?s.offsetWidth:t,r=i?s.offsetHeight:e;return (Math.round(t)!==n||Math.round(e)!==r)&&(t=n,e=r),{width:t,height:e}};export{l as a};//# sourceMappingURL=chunk-X7ZJXXGU.js.map
+//# sourceMappingURL=chunk-X7ZJXXGU.js.map

package/dist/{chunk-TJWADQ7V.js.map → chunk-X7ZJXXGU.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/get-css-dimensions/get-css-dimensions.ts"],"names":["getCssDimensions","element","css","getComputedStyle","width","height","hasOffset","isHTMLElement","offsetWidth","offsetHeight"],"mappings":"+EAoBO,IAAMA,CAAAA,CAAoBC,CAAAA,EAAkD,CACjF,IAAMC,CAAAA,CAAMC,EAAiBF,CAAO,CAAA,CAIhCG,CAAAA,CAAQ,UAAA,CAAWF,CAAAA,CAAI,KAAK,GAAK,CAAA,CACjCG,CAAAA,CAAS,UAAA,CAAWH,CAAAA,CAAI,MAAM,CAAA,EAAK,CAAA,CAEjCI,CAAAA,CAAYC,GAAAA,CAAcN,CAAO,CAAA,CACjCO,CAAAA,CAAcF,CAAAA,CAAYL,CAAAA,CAAQ,YAAcG,CAAAA,CAChDK,CAAAA,CAAeH,CAAAA,CAAYL,CAAAA,CAAQ,YAAA,CAAeI,CAAAA,CAGxD,QAFuB,IAAA,CAAK,KAAA,CAAMD,CAAK,CAAA,GAAMI,CAAAA,EAAe,IAAA,CAAK,MAAMH,CAAM,CAAA,GAAMI,CAAAA,IAGjFL,CAAAA,CAAQI,CAAAA,CACRH,CAAAA,CAASI,CAAAA,CAAAA,CAGJ,CACL,KAAA,CAAAL,CAAAA,CACA,MAAA,CAAAC,CACF,CACF","file":"chunk-TJWADQ7V.js","sourcesContent":["import type { GetCssDimensionsReturnValue } from './get-css-dimensions.types';\nimport { getComputedStyle } from '../get-computed-style';\nimport { isHTMLElement } from '../is-html-element';\n\n/**\n * Calculates the visual dimensions of an element, reconciling CSS styles with layout geometry.\n *\n * This utility determines the most accurate width and height of an element by\n * comparing its computed CSS values with its offset dimensions. It accounts for\n * edge cases where `getComputedStyle` might return inconsistent results, such as\n * in testing environments or when dealing with SVG elements. If a significant\n * discrepancy is detected between the CSS-defined size and the actual offset size,\n * it prioritizes the offset dimensions to ensure layout accuracy.\n *\n * @example\n * ```ts\n * getCssDimensions(myElement);\n * // Returns: { width: 150, height: 42 }\n * ```\n */\nexport const getCssDimensions = (element: Element): GetCssDimensionsReturnValue => {\n  const css = getComputedStyle(element);\n\n  // In testing environments, the `width` and `height` properties are empty\n  // strings for SVG elements, returning NaN. Fallback to `0` in this case.\n  let width = parseFloat(css.width) || 0;\n  let height = parseFloat(css.height) || 0;\n\n  const hasOffset = isHTMLElement(element);\n  const offsetWidth = hasOffset ? element.offsetWidth : width;\n  const offsetHeight = hasOffset ? element.offsetHeight : height;\n  const shouldFallback = Math.round(width) !== offsetWidth || Math.round(height) !== offsetHeight;\n\n  if (shouldFallback) {\n    width = offsetWidth;\n    height = offsetHeight;\n  }\n\n  return {\n    width,\n    height,\n  };\n};\n"]}
+{"version":3,"sources":["../src/get-css-dimensions/get-css-dimensions.ts"],"names":["getCssDimensions","element","css","getComputedStyle","width","height","hasOffset","isHTMLElement","offsetWidth","offsetHeight"],"mappings":"+EAoBO,IAAMA,CAAAA,CAAoBC,CAAAA,EAAkD,CACjF,IAAMC,CAAAA,CAAMC,EAAiBF,CAAO,CAAA,CAIhCG,CAAAA,CAAQ,UAAA,CAAWF,CAAAA,CAAI,KAAK,GAAK,CAAA,CACjCG,CAAAA,CAAS,UAAA,CAAWH,CAAAA,CAAI,MAAM,CAAA,EAAK,CAAA,CAEjCI,CAAAA,CAAYC,GAAAA,CAAcN,CAAO,CAAA,CACjCO,CAAAA,CAAcF,CAAAA,CAAYL,CAAAA,CAAQ,YAAcG,CAAAA,CAChDK,CAAAA,CAAeH,CAAAA,CAAYL,CAAAA,CAAQ,YAAA,CAAeI,CAAAA,CAGxD,QAFuB,IAAA,CAAK,KAAA,CAAMD,CAAK,CAAA,GAAMI,CAAAA,EAAe,IAAA,CAAK,MAAMH,CAAM,CAAA,GAAMI,CAAAA,IAGjFL,CAAAA,CAAQI,CAAAA,CACRH,CAAAA,CAASI,CAAAA,CAAAA,CAGJ,CACL,KAAA,CAAAL,CAAAA,CACA,MAAA,CAAAC,CACF,CACF","file":"chunk-X7ZJXXGU.js","sourcesContent":["import type { GetCssDimensionsReturnValue } from './get-css-dimensions.types';\nimport { getComputedStyle } from '../get-computed-style';\nimport { isHTMLElement } from '../is-html-element';\n\n/**\n * Calculates the visual dimensions of an element, reconciling CSS styles with layout geometry.\n *\n * This utility determines the most accurate width and height of an element by\n * comparing its computed CSS values with its offset dimensions. It accounts for\n * edge cases where `getComputedStyle` might return inconsistent results, such as\n * in testing environments or when dealing with SVG elements. If a significant\n * discrepancy is detected between the CSS-defined size and the actual offset size,\n * it prioritizes the offset dimensions to ensure layout accuracy.\n *\n * @example\n * ```ts\n * getCssDimensions(myElement);\n * // Returns: { width: 150, height: 42 }\n * ```\n */\nexport const getCssDimensions = (element: Element): GetCssDimensionsReturnValue => {\n  const css = getComputedStyle(element);\n\n  // In testing environments, the `width` and `height` properties are empty\n  // strings for SVG elements, returning NaN. Fallback to `0` in this case.\n  let width = parseFloat(css.width) || 0;\n  let height = parseFloat(css.height) || 0;\n\n  const hasOffset = isHTMLElement(element);\n  const offsetWidth = hasOffset ? element.offsetWidth : width;\n  const offsetHeight = hasOffset ? element.offsetHeight : height;\n  const shouldFallback = Math.round(width) !== offsetWidth || Math.round(height) !== offsetHeight;\n\n  if (shouldFallback) {\n    width = offsetWidth;\n    height = offsetHeight;\n  }\n\n  return {\n    width,\n    height,\n  };\n};\n"]}

package/dist/clamp/index.d.ts

@@ -2,26 +2,21 @@
  * Configuration object for the `clamp` utility.
  *
  * This interface defines the numerical boundaries and the target value required
- * to perform a clamping operation. It ensures that all provided properties are
- * valid, finite numbers, maintaining strict mathematical constraints where
- * the minimum bound must not exceed the maximum bound.
+ * to perform a clamping operation.
  */
 interface ClampParams {
     /**
      * The numerical value to be restricted within the specified range.
-     * Must be a finite number.
      */
     value: number;
     /**
      * The lower bound of the range.
      * If `value` is less than `min`, the function returns `min`.
-     * Must be a finite number and less than or equal to `max`.
      */
     min: number;
     /**
      * The upper bound of the range.
      * If `value` is greater than `max`, the function returns `max`.
-     * Must be a finite number and greater than or equal to `min`.
      */
     max: number;
 }
@@ -33,17 +28,13 @@ interface ClampParams {
  * If the input value is smaller than the minimum boundary, the minimum value is
  * returned. If it exceeds the maximum boundary, the maximum value is returned.
  *
- * This function will throw an error if:
- * - Any of the input parameters are not finite numbers.
- * - The `min` value is greater than the `max` value.
- *
  * @example
  * ```ts
  * clamp({ value: 150, min: 0, max: 100 });
  * // Returns: 100
  *
  * clamp({ value: -20, min: 0, max: 100 });
- * Returns: 0
+ * // Returns: 0
  *
  * clamp({ value: 50, min: 0, max: 100 });
  * // Returns: 50

package/dist/clamp/index.js

@@ -1,2 +1,2 @@
-export{a as clamp}from'../chunk-BVBN4VWU.js';import'../chunk-TAV72HQS.js';import'../chunk-O4WYO5SA.js';//# sourceMappingURL=index.js.map
+export{a as clamp}from'../chunk-AYPZYNVX.js';//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/copy-to-clipboard/index.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Represents a structured error object returned when a clipboard operation fails.
+ *
+ * This interface provides a uniform error shape to distinguish between
+ * environment-level limitations and unexpected runtime failures,
+ * allowing consumers to handle each case appropriately.
+ */
+interface ClipboardError {
+    /**
+     * The classification of the failure.
+     * - `"NOT_SUPPORTED"`: The browser lacks `navigator.clipboard.writeText` support.
+     * - `"COPY_FAILED"`: The operation was rejected (e.g., lack of permissions).
+     */
+    type: 'NOT_SUPPORTED' | 'COPY_FAILED';
+    /**
+     * A descriptive message detailing the cause of the failure.
+     * This field is populated exclusively when the error `type` is `"COPY_FAILED"`,
+     * typically containing the message from the native `Error` object.
+     */
+    message?: string;
+}
+/**
+ * Configuration object for the `copyToClipboard` utility.
+ *
+ * This interface encapsulates the parameters required to perform a clipboard write operation.
+ * It allows the caller to define custom behavior for both successful data persistence
+ * and potential browser-level restrictions or runtime failures through dedicated
+ * callback handlers.
+ */
+interface CopyToClipboardParams {
+    /**
+     * The plaintext string to be transferred to the system clipboard.
+     * This value is processed as a standard UTF-16 string by the Clipboard API.
+     */
+    value: string;
+    /**
+     * An optional callback executed immediately after the value has been successfully
+     * written to the clipboard. Use this to trigger UI feedback like "Copied!" toasts
+     * or success state updates.
+     *
+     * @default undefined
+     */
+    onSuccess?: () => void;
+    /**
+     * An optional callback executed when the copy operation fails or is not supported.
+     * It provides structured error information to distinguish between environment
+     * limitations (`"NOT_SUPPORTED"`) and unexpected runtime rejections (`"COPY_FAILED"`).
+     *
+     * @default undefined
+     */
+    onError?: (error: ClipboardError) => void;
+}
+
+/**
+ * Asynchronously transfers text to the system clipboard using the Clipboard API.
+ *
+ * This utility provides a structured wrapper around `navigator.clipboard.writeText`,
+ * offering specific error types to distinguish between unsupported environments
+ * and runtime failures.
+ *
+ * This function expects a browser environment where `window` or
+ * `document` is globally available.
+ *
+ * @example
+ * ```ts
+ * copyToClipboard({
+ * 	value: "Hello World",
+ * 	onSuccess: () => console.log("Text copied!"),
+ * 	onError: (err) => console.error(`Copy failed: ${err.type}, ${err.message}`),
+ * });
+ * ```
+ */
+declare const copyToClipboard: (params: CopyToClipboardParams) => Promise<void>;
+
+export { type ClipboardError, type CopyToClipboardParams, copyToClipboard };

package/dist/copy-to-clipboard/index.js

@@ -0,0 +1,2 @@
+export{a as copyToClipboard}from'../chunk-P7NW64IN.js';//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/copy-to-clipboard/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/focus-element/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Configuration object for the `focusElement` utility.
+ *
+ * This interface encapsulates the parameters required to programmatically manage
+ * focus on a specific DOM element. It provides options to control visual focus
+ * indicators, scroll behavior, and automatic text selection for input fields.
+ */
+interface FocusElementParams {
+    /**
+     * The target HTML element that should receive focus.
+     * This element will be focused using the native `HTMLElement.focus()` method.
+     */
+    element: HTMLElement;
+    /**
+     * Whether the focus indicator (e.g., focus ring) should be visible.
+     * This mimics the behavior of the `:focus-visible` CSS pseudo-class,
+     * ensuring the element appears focused to the user, typically used for
+     * keyboard navigation consistency.
+     *
+     * @default false
+     */
+    focusVisible?: boolean;
+    /**
+     * Whether the browser should scroll the element into view after focusing.
+     * If set to `true`, it prevents the default scrolling behavior.
+     *
+     * @default false
+     */
+    preventScroll?: boolean;
+    /**
+     * Whether to select the text content within the element.
+     * Selection is only performed if the element is an `HTMLInputElement`,
+     * supports selection, and is not already the currently focused element.
+     *
+     * @default false
+     */
+    select?: boolean;
+}
+
+/**
+ * Programmatically manages focus for a given DOM element with extended configuration.
+ *
+ * This utility wraps the native `HTMLElement.focus()` method, providing a unified
+ * interface for common focus-related tasks such as controlling the focus ring
+ * visibility, preventing automatic scrolling, and selecting input text.
+ *
+ * It includes a safety check to ensure the target element is focusable and
+ * optimizes the user experience by avoiding redundant selection operations
+ * if the element is already active.
+ *
+ * @example
+ * ```ts
+ * // Basic focus with scroll prevention
+ * focusElement({ element: myButton, preventScroll: true });
+ *
+ * // Focus an input and automatically select its text content
+ * focusElement({ element: myInput, select: true });
+ *
+ * // Requesting selection on an already active element will focus it without re-selecting
+ * focusElement({ element: alreadyActiveInput, select: true });
+ *
+ * // Triggering focus with a visible focus ring (mimics keyboard navigation)
+ * focusElement({ element: myLink, focusVisible: true });
+ * ```
+ */
+declare const focusElement: (params: FocusElementParams) => void;
+
+export { type FocusElementParams, focusElement };

package/dist/focus-element/index.js

@@ -0,0 +1,2 @@
+export{a as focusElement}from'../chunk-ATOIAGQE.js';import'../chunk-WWLZE6DE.js';import'../chunk-QVG7VOJQ.js';import'../chunk-EQONVDWV.js';//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/focus-element/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/focus-first-element/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Configuration object for the `focusFirstElement` utility.
+ *
+ * This interface defines the parameters for attempting to shift focus to the first
+ * available and valid element from a list of potential candidates. It provides
+ * options to control visual focus indicators, scroll behavior, and text selection.
+ */
+interface FocusFirstElementParams {
+    /**
+     * An ordered array of DOM elements to be evaluated for focusing.
+     * The utility iterates through this list and attempts to focus each element
+     * sequentially until one successfully receives focus.
+     */
+    candidates: HTMLElement[];
+    /**
+     * Whether the focus indicator (e.g., focus ring) should be visible.
+     * This mimics the behavior of the `:focus-visible` CSS pseudo-class,
+     * ensuring the element appears focused to the user, typically used for
+     * keyboard navigation consistency.
+     *
+     * @default false
+     */
+    focusVisible?: boolean;
+    /**
+     * Whether the browser should scroll the element into view after focusing.
+     * If set to `true`, it prevents the default scrolling behavior, which is
+     * useful for maintaining the current viewport position.
+     *
+     * @default false
+     */
+    preventScroll?: boolean;
+    /**
+     * Whether to select the text content within the candidate element.
+     * Selection is only performed if the focused candidate is an `HTMLInputElement`
+     * that supports text selection.
+     *
+     * @default false
+     */
+    select?: boolean;
+}
+
+/**
+ * Attempts to focus the first available element from a list of candidates.
+ *
+ * This function iterates through an array of elements and tries to set focus on each
+ * one sequentially. The process stops as soon as an element successfully receives focus
+ * (i.e., when the document's active element changes). This is particularly useful for
+ * managing focus in modals, forms, or complex components where the primary focus target
+ * might be conditional or dynamic.
+ *
+ * @example
+ * ```ts
+ * // Focus the first visible input or fallback to a close button
+ * focusFirstElement({ candidates: [input, closeButton], select: true });
+ *
+ * // Attempt to focus multiple elements, preventing scroll on the successful one
+ * focusFirstElement({ candidates: [primaryAction, secondaryAction], preventScroll: true });
+ * ```
+ */
+declare const focusFirstElement: (params: FocusFirstElementParams) => void;
+
+export { type FocusFirstElementParams, focusFirstElement };

package/dist/focus-first-element/index.js

@@ -0,0 +1,2 @@
+export{a as focusFirstElement}from'../chunk-TOBJAPHB.js';import'../chunk-ATOIAGQE.js';import'../chunk-WWLZE6DE.js';import'../chunk-QVG7VOJQ.js';import'../chunk-EQONVDWV.js';//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/focus-first-element/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/get-active-element/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Recursively retrieves the currently focused element, including those nested within Shadow DOM.
+ *
+ * Unlike the standard `document.activeElement`, which only returns the host element
+ * of a Shadow Root, this utility traverses through any available `shadowRoot` to
+ * pinpoint the actual element that holds focus deep within the DOM tree.
+ *
+ * @example
+ * ```ts
+ * // If focus is inside a web component's shadow DOM:
+ * getActiveElement(document);
+ * // Returns: <input /> (inside shadow root)
+ *
+ * // Standard approach would only return:
+ * document.activeElement;
+ * // Returns: <my-custom-component /> (the host)
+ * ```
+ */
+declare const getActiveElement: (doc: Document) => Element | null;
+
+export { getActiveElement };

package/dist/get-active-element/index.js

@@ -0,0 +1,2 @@
+export{a as getActiveElement}from'../chunk-QVG7VOJQ.js';//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/get-active-element/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/get-css-dimensions/index.js

@@ -1,2 +1,2 @@
-export{a as getCssDimensions}from'../chunk-TJWADQ7V.js';import'../chunk-KSDRQLOI.js';import'../chunk-V3434ODU.js';import'../chunk-5BI2X7JA.js';import'../chunk-H2U5U7XY.js';//# sourceMappingURL=index.js.map
+export{a as getCssDimensions}from'../chunk-X7ZJXXGU.js';import'../chunk-5BI2X7JA.js';import'../chunk-RTJWUKV6.js';import'../chunk-H2U5U7XY.js';import'../chunk-V3434ODU.js';//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/get-document/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Retrieves the document object associated with a given DOM node, ensuring the correct execution context.
+ *
+ * This utility identifies the correct owner document for a specific node. It is
+ * particularly useful when working with applications that utilize iframes or
+ * multiple windows, as it ensures that document-level APIs (like `createElement`,
+ * `getElementById`, or `addEventListener`) are accessed from the node's actual
+ * environment rather than the current global document.
+ *
+ * @example
+ * ```ts
+ * getDocument(document.getElementById("my-element"));
+ * // Returns: the document object where the element resides
+ *
+ * getDocument(null);
+ * // Returns: the global document object as a fallback
+ * ```
+ */
+declare const getDocument: (node: any) => Document;
+
+export { getDocument };

package/dist/get-document/index.js

@@ -0,0 +1,2 @@
+export{a as getDocument}from'../chunk-EQONVDWV.js';//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/get-document/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/get-hidden-element-height/index.js

@@ -1,2 +1,2 @@
-export{a as getHiddenElementHeight}from'../chunk-RZEIOZGJ.js';import'../chunk-TJWADQ7V.js';import'../chunk-KSDRQLOI.js';import'../chunk-V3434ODU.js';import'../chunk-5BI2X7JA.js';import'../chunk-H2U5U7XY.js';//# sourceMappingURL=index.js.map
+export{a as getHiddenElementHeight}from'../chunk-R2W6HH4I.js';import'../chunk-X7ZJXXGU.js';import'../chunk-5BI2X7JA.js';import'../chunk-RTJWUKV6.js';import'../chunk-H2U5U7XY.js';import'../chunk-V3434ODU.js';//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.d.ts

@@ -1,13 +1,19 @@
 export { AddEventListenerOnceParams, AllEventMaps, addEventListenerOnce } from './add-event-listener-once/index.js';
 export { ClampParams, clamp } from './clamp/index.js';
+export { ClipboardError, CopyToClipboardParams, copyToClipboard } from './copy-to-clipboard/index.js';
 export { ErrorParams, error } from './error/index.js';
 export { FailParams, fail } from './fail/index.js';
+export { FocusElementParams, focusElement } from './focus-element/index.js';
+export { FocusFirstElementParams, focusFirstElement } from './focus-first-element/index.js';
+export { getActiveElement } from './get-active-element/index.js';
 export { getComputedStyle } from './get-computed-style/index.js';
 export { GetCssDimensionsReturnValue, getCssDimensions } from './get-css-dimensions/index.js';
+export { getDocument } from './get-document/index.js';
 export { getHiddenElementHeight } from './get-hidden-element-height/index.js';
 export { getWindow } from './get-window/index.js';
 export { hasWindow } from './has-window/index.js';
 export { isHTMLElement } from './is-html-element/index.js';
+export { isSelectableInput } from './is-selectable-input/index.js';
 export { isValidNumber } from './is-valid-number/index.js';
 export { PossibleStyle, mergeStyles } from './merge-styles/index.js';
 export { HTMLElementWithScrollIntoViewIfNeeded, ScrollIntoViewIfNeededParams, scrollIntoViewIfNeeded } from './scroll-into-view-if-needed/index.js';
@@ -15,3 +21,4 @@ export { visuallyHiddenInputStyle } from './visually-hidden-input-style/index.js
 export { visuallyHiddenStyle } from './visually-hidden-style/index.js';
 export { wait } from './wait/index.js';
 export { WarnParams, warn } from './warn/index.js';
+export { WrapArrayParams, wrapArray } from './wrap-array/index.js';

package/dist/index.js

@@ -1,2 +1,2 @@
-export{a as warn}from'./chunk-6L6DIP5N.js';export{a as mergeStyles}from'./chunk-NBN5PUZ6.js';export{a as scrollIntoViewIfNeeded}from'./chunk-YFUOSM2Q.js';export{a as visuallyHiddenInputStyle}from'./chunk-AYHMR4G2.js';export{a as visuallyHiddenStyle}from'./chunk-YRBGPPKC.js';export{a as wait}from'./chunk-OUZ54COH.js';export{a as addEventListenerOnce}from'./chunk-GLPQ4KOF.js';export{a as clamp}from'./chunk-BVBN4VWU.js';export{a as isValidNumber}from'./chunk-TAV72HQS.js';export{a as error}from'./chunk-GG6DRWSS.js';export{a as fail}from'./chunk-O4WYO5SA.js';export{a as getHiddenElementHeight}from'./chunk-RZEIOZGJ.js';export{a as getCssDimensions}from'./chunk-TJWADQ7V.js';export{a as isHTMLElement}from'./chunk-KSDRQLOI.js';export{a as hasWindow}from'./chunk-V3434ODU.js';export{a as getComputedStyle}from'./chunk-5BI2X7JA.js';export{a as getWindow}from'./chunk-H2U5U7XY.js';//# sourceMappingURL=index.js.map
+export{a as wrapArray}from'./chunk-IUHRHZ62.js';export{a as isValidNumber}from'./chunk-TAV72HQS.js';export{a as mergeStyles}from'./chunk-NBN5PUZ6.js';export{a as scrollIntoViewIfNeeded}from'./chunk-YFUOSM2Q.js';export{a as visuallyHiddenInputStyle}from'./chunk-AYHMR4G2.js';export{a as visuallyHiddenStyle}from'./chunk-YRBGPPKC.js';export{a as wait}from'./chunk-OUZ54COH.js';export{a as warn}from'./chunk-6L6DIP5N.js';export{a as getHiddenElementHeight}from'./chunk-R2W6HH4I.js';export{a as getCssDimensions}from'./chunk-X7ZJXXGU.js';export{a as getComputedStyle}from'./chunk-5BI2X7JA.js';export{a as isHTMLElement}from'./chunk-RTJWUKV6.js';export{a as getWindow}from'./chunk-H2U5U7XY.js';export{a as hasWindow}from'./chunk-V3434ODU.js';export{a as addEventListenerOnce}from'./chunk-GLPQ4KOF.js';export{a as clamp}from'./chunk-AYPZYNVX.js';export{a as copyToClipboard}from'./chunk-P7NW64IN.js';export{a as error}from'./chunk-GG6DRWSS.js';export{a as fail}from'./chunk-O4WYO5SA.js';export{a as focusFirstElement}from'./chunk-TOBJAPHB.js';export{a as focusElement}from'./chunk-ATOIAGQE.js';export{a as isSelectableInput}from'./chunk-WWLZE6DE.js';export{a as getActiveElement}from'./chunk-QVG7VOJQ.js';export{a as getDocument}from'./chunk-EQONVDWV.js';//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/is-html-element/index.js

@@ -1,2 +1,2 @@
-export{a as isHTMLElement}from'../chunk-KSDRQLOI.js';import'../chunk-V3434ODU.js';import'../chunk-H2U5U7XY.js';//# sourceMappingURL=index.js.map
+export{a as isHTMLElement}from'../chunk-RTJWUKV6.js';import'../chunk-H2U5U7XY.js';import'../chunk-V3434ODU.js';//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/is-selectable-input/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Determines whether a given HTML element is an input that supports text selection.
+ *
+ * This utility performs a type guard check to verify if the element is an instance
+ * of `HTMLInputElement` and explicitly contains the `select` method. This is
+ * particularly useful before calling `element.select()` to avoid runtime errors
+ * on input types that do not support selection (e.g., `type="date"` in some browsers).
+ *
+ * @example
+ * ```ts
+ * const input = document.querySelector('input[type="text"]');
+ *
+ * if (isSelectableInput(input)) {
+ * 	input.select();
+ * }
+ * ```
+ */
+declare const isSelectableInput: (element: HTMLElement) => element is HTMLInputElement;
+
+export { isSelectableInput };

package/dist/is-selectable-input/index.js

@@ -0,0 +1,2 @@
+export{a as isSelectableInput}from'../chunk-WWLZE6DE.js';//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/is-selectable-input/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/wrap-array/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Configuration object for the `wrapArray` utility.
+ *
+ * This interface defines the necessary parameters to perform a circular shift
+ * on a generic collection. It ensures type safety by leveraging a generic type `T`,
+ * allowing the utility to maintain the integrity of the array elements throughout
+ * the rearrangement process.
+ */
+interface WrapArrayParams<T> {
+    /**
+     * The source array to be rearranged.
+     * This array remains unmodified as the function returns a new mapped instance.
+     */
+    array: T[];
+    /**
+     * The zero-based index in the original array that will serve as the new starting point.
+     * Elements before this index will be appended to the end of the new array,
+     * maintaining their relative order in a circular fashion.
+     */
+    startIndex: number;
+}
+
+/**
+ * Rearranges an array by shifting its starting point to a specified index.
+ *
+ * This utility creates a circular shift of the array elements. The element at
+ * `startIndex` becomes the first element of the resulting array, followed by
+ * subsequent elements. When the end of the original array is reached, it wraps
+ * around to the beginning until all elements are included.
+ *
+ * @example
+ * ```ts
+ * wrapArray({ array: ["a", "b", "c", "d"], startIndex: 2 });
+ * // Returns: ["c", "d", "a", "b"]
+ *
+ * wrapArray({ array: ["a", "b", "c", "d"], startIndex: 3 });
+ * // Returns: ["d", "a", "b", "c"]
+ *
+ * wrapArray({ array: ["a", "b", "c", "d"], startIndex: 0 });
+ * // Returns: ["a", "b", "c", "d"]
+ * ```
+ */
+declare const wrapArray: <T>(params: WrapArrayParams<T>) => T[];
+
+export { type WrapArrayParams, wrapArray };

package/dist/wrap-array/index.js

@@ -0,0 +1,2 @@
+export{a as wrapArray}from'../chunk-IUHRHZ62.js';//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/wrap-array/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@entry-ui/utilities",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "",
   "keywords": [],
   "homepage": "https://github.com/ZAHON/entry-ui/tree/main/packages/utilities#readme",

package/dist/chunk-BVBN4VWU.js

@@ -1,2 +0,0 @@
-import {a}from'./chunk-TAV72HQS.js';import {a as a$1}from'./chunk-O4WYO5SA.js';var s=r=>{let{value:m,min:e,max:i}=r;return a(m)||a$1({prefix:"[Entry UI Utilities]",messages:["Invalid 'value' parameter in 'clamp' utility.",`Expected a finite number, but received: ${m}`]}),a(e)||a$1({prefix:"[Entry UI Utilities]",messages:["Invalid 'min' parameter in 'clamp' utility.",`Expected a finite number, but received: ${e}`]}),a(i)||a$1({prefix:"[Entry UI Utilities]",messages:["Invalid 'max' parameter in 'clamp' utility.",`Expected a finite number, but received: ${i}`]}),e>i&&a$1({prefix:"[Entry UI Utilities]",messages:["Invalid range for 'clamp' utility.",`The 'min' parameter (${e}) must be less than or equal to the 'max' parameter (${i}).`]}),Math.min(i,Math.max(e,m))};export{s as a};//# sourceMappingURL=chunk-BVBN4VWU.js.map
-//# sourceMappingURL=chunk-BVBN4VWU.js.map

package/dist/chunk-BVBN4VWU.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/clamp/clamp.ts"],"names":["clamp","params","value","min","max","isValidNumber","fail"],"mappings":"+EA2BO,IAAMA,EAASC,CAAAA,EAAwB,CAC5C,GAAM,CAAE,KAAA,CAAAC,EAAO,GAAA,CAAAC,CAAAA,CAAK,GAAA,CAAAC,CAAI,EAAIH,CAAAA,CAE5B,OAAKI,EAAcH,CAAK,CAAA,EACtBI,IAAK,CACH,MAAA,CAAQ,sBAAA,CACR,QAAA,CAAU,CAAC,+CAAA,CAAiD,CAAA,wCAAA,EAA2CJ,CAAK,CAAA,CAAE,CAChH,CAAC,CAAA,CAGEG,CAAAA,CAAcF,CAAG,CAAA,EACpBG,GAAAA,CAAK,CACH,MAAA,CAAQ,sBAAA,CACR,SAAU,CAAC,6CAAA,CAA+C,2CAA2CH,CAAG,CAAA,CAAE,CAC5G,CAAC,EAGEE,CAAAA,CAAcD,CAAG,GACpBE,GAAAA,CAAK,CACH,OAAQ,sBAAA,CACR,QAAA,CAAU,CAAC,6CAAA,CAA+C,CAAA,wCAAA,EAA2CF,CAAG,CAAA,CAAE,CAC5G,CAAC,CAAA,CAGCD,CAAAA,CAAMC,GACRE,GAAAA,CAAK,CACH,MAAA,CAAQ,sBAAA,CACR,SAAU,CACR,oCAAA,CACA,wBAAwBH,CAAG,CAAA,qDAAA,EAAwDC,CAAG,CAAA,EAAA,CACxF,CACF,CAAC,CAAA,CAGI,IAAA,CAAK,IAAIA,CAAAA,CAAK,IAAA,CAAK,IAAID,CAAAA,CAAKD,CAAK,CAAC,CAC3C","file":"chunk-BVBN4VWU.js","sourcesContent":["import type { ClampParams } from './clamp.types';\nimport { isValidNumber } from '../is-valid-number';\nimport { fail } from '../fail';\n\n/**\n * Clamps a number between a minimum and maximum value.\n *\n * This utility ensures that the returned value is restricted to a specified range.\n * If the input value is smaller than the minimum boundary, the minimum value is\n * returned. If it exceeds the maximum boundary, the maximum value is returned.\n *\n * This function will throw an error if:\n * - Any of the input parameters are not finite numbers.\n * - The `min` value is greater than the `max` value.\n *\n * @example\n * ```ts\n * clamp({ value: 150, min: 0, max: 100 });\n * // Returns: 100\n *\n * clamp({ value: -20, min: 0, max: 100 });\n * Returns: 0\n *\n * clamp({ value: 50, min: 0, max: 100 });\n * // Returns: 50\n * ```\n */\nexport const clamp = (params: ClampParams) => {\n  const { value, min, max } = params;\n\n  if (!isValidNumber(value)) {\n    fail({\n      prefix: '[Entry UI Utilities]',\n      messages: [`Invalid 'value' parameter in 'clamp' utility.`, `Expected a finite number, but received: ${value}`],\n    });\n  }\n\n  if (!isValidNumber(min)) {\n    fail({\n      prefix: '[Entry UI Utilities]',\n      messages: [`Invalid 'min' parameter in 'clamp' utility.`, `Expected a finite number, but received: ${min}`],\n    });\n  }\n\n  if (!isValidNumber(max)) {\n    fail({\n      prefix: '[Entry UI Utilities]',\n      messages: [`Invalid 'max' parameter in 'clamp' utility.`, `Expected a finite number, but received: ${max}`],\n    });\n  }\n\n  if (min > max) {\n    fail({\n      prefix: '[Entry UI Utilities]',\n      messages: [\n        `Invalid range for 'clamp' utility.`,\n        `The 'min' parameter (${min}) must be less than or equal to the 'max' parameter (${max}).`,\n      ],\n    });\n  }\n\n  return Math.min(max, Math.max(min, value));\n};\n"]}

package/dist/chunk-KSDRQLOI.js

@@ -1,2 +0,0 @@
-import {a}from'./chunk-V3434ODU.js';import {a as a$1}from'./chunk-H2U5U7XY.js';var i=e=>a()?e instanceof HTMLElement||e instanceof a$1(e).HTMLElement:false;export{i as a};//# sourceMappingURL=chunk-KSDRQLOI.js.map
-//# sourceMappingURL=chunk-KSDRQLOI.js.map