@entry-ui/utilities 0.5.0 → 0.7.0

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-YFUOSM2Q.js

@@ -0,0 +1,2 @@
+var r=t=>{let{element:e,center:o=true}=t;"scrollIntoViewIfNeeded"in e?e.scrollIntoViewIfNeeded(o):e.scrollIntoView({behavior:"auto",block:o?"center":"nearest",inline:"nearest"});};export{r as a};//# sourceMappingURL=chunk-YFUOSM2Q.js.map
+//# sourceMappingURL=chunk-YFUOSM2Q.js.map

package/dist/chunk-YFUOSM2Q.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/scroll-into-view-if-needed/scroll-into-view-if-needed.ts"],"names":["scrollIntoViewIfNeeded","params","element","center"],"mappings":"AA0BO,IAAMA,CAAAA,CAA0BC,CAAAA,EAAyC,CAC9E,GAAM,CAAE,OAAA,CAAAC,CAAAA,CAAS,MAAA,CAAAC,CAAAA,CAAS,IAAK,CAAA,CAAIF,CAAAA,CAE/B,2BAA4BC,CAAAA,CACbA,CAAAA,CAER,sBAAA,CAAuBC,CAAM,CAAA,CAEtCD,CAAAA,CAAQ,cAAA,CAAe,CACrB,QAAA,CAAU,MAAA,CACV,KAAA,CAAOC,CAAAA,CAAS,QAAA,CAAW,SAAA,CAC3B,MAAA,CAAQ,SACV,CAAC,EAEL","file":"chunk-YFUOSM2Q.js","sourcesContent":["import type {\n  ScrollIntoViewIfNeededParams,\n  HTMLElementWithScrollIntoViewIfNeeded,\n} from './scroll-into-view-if-needed.types';\n\n/**\n * Ensures an element is visible in the viewport by scrolling to it only if necessary.\n *\n * This utility provides a unified interface for the non-standard `scrollIntoViewIfNeeded`\n * method (available in Chromium and WebKit) while providing a robust fallback to the\n * standard `scrollIntoView` API for other browsers. It is designed to prevent jarring\n * layout jumps by avoiding redundant scrolls if the element is already within the\n * user's visible area.\n *\n * The function allows for flexible positioning, enabling you to either center the\n * element within the viewport or use a minimal `\"nearest\"` alignment strategy to\n * reduce visual noise during navigation or search-in-page operations.\n *\n * @example\n * ```ts\n * scrollIntoViewIfNeeded({\n * element: document.querySelector(\"#target-element\"),\n * center: true\n * });\n * ```\n */\nexport const scrollIntoViewIfNeeded = (params: ScrollIntoViewIfNeededParams) => {\n  const { element, center = true } = params;\n\n  if ('scrollIntoViewIfNeeded' in element) {\n    const _element = element as HTMLElementWithScrollIntoViewIfNeeded;\n\n    _element.scrollIntoViewIfNeeded(center);\n  } else {\n    element.scrollIntoView({\n      behavior: 'auto',\n      block: center ? 'center' : 'nearest',\n      inline: 'nearest',\n    });\n  }\n};\n"]}

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/index.d.ts

@@ -1,5 +1,6 @@
 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 { getComputedStyle } from './get-computed-style/index.js';
@@ -10,6 +11,7 @@ export { hasWindow } from './has-window/index.js';
 export { isHTMLElement } from './is-html-element/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';
 export { visuallyHiddenInputStyle } from './visually-hidden-input-style/index.js';
 export { visuallyHiddenStyle } from './visually-hidden-style/index.js';
 export { wait } from './wait/index.js';

package/dist/index.js

@@ -1,2 +1,2 @@
-export{a as mergeStyles}from'./chunk-NBN5PUZ6.js';export{a as visuallyHiddenStyle}from'./chunk-YRBGPPKC.js';export{a as visuallyHiddenInputStyle}from'./chunk-AYHMR4G2.js';export{a as wait}from'./chunk-OUZ54COH.js';export{a as warn}from'./chunk-6L6DIP5N.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 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-RZEIOZGJ.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 addEventListenerOnce}from'./chunk-GLPQ4KOF.js';export{a as clamp}from'./chunk-BVBN4VWU.js';export{a as isValidNumber}from'./chunk-TAV72HQS.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 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
 //# sourceMappingURL=index.js.map

package/dist/scroll-into-view-if-needed/index.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Configuration object for the `scrollIntoViewIfNeeded` utility.
+ *
+ * This interface encapsulates the parameters required to ensure an element's visibility.
+ * It provides a structured way to pass the target element and visual alignment
+ * preferences, allowing the utility to choose between native Chromium/WebKit
+ * implementations or a standard CSSOM Scroll Customization fallback.
+ */
+interface ScrollIntoViewIfNeededParams {
+    /**
+     * The DOM element to be brought into the visible area of the viewport.
+     * This is the primary target for the scroll operation, ensuring the element
+     * is accessible to the user's current line of sight.
+     */
+    element: HTMLElement;
+    /**
+     * Controls the positioning logic for the scroll alignment.
+     * When set to `true`, the utility attempts to place the element in the dead center
+     * of the viewport. When `false`, it uses the `"nearest"` alignment strategy,
+     * minimizing movement if the element is already partially visible.
+     *
+     * @default true
+     */
+    center?: boolean;
+}
+/**
+ * Type extension for the `HTMLElement` interface to include non-standard scroll methods.
+ *
+ * This interface is used for type casting and safety checks when interacting with
+ * browser-specific DOM APIs. It explicitly defines the `scrollIntoViewIfNeeded`
+ * method, which is natively supported in Chromium and WebKit-based engines but
+ * missing from the standard TypeScript `HTMLElement` definition.
+ */
+interface HTMLElementWithScrollIntoViewIfNeeded extends HTMLElement {
+    /**
+     * A non-standard, Chromium and WebKit-specific method that scrolls the element
+     * into the visible area of the browser window only if it is not already within
+     * the current viewport.
+     */
+    scrollIntoViewIfNeeded: (centerIfNeeded?: boolean) => void;
+}
+
+/**
+ * Ensures an element is visible in the viewport by scrolling to it only if necessary.
+ *
+ * This utility provides a unified interface for the non-standard `scrollIntoViewIfNeeded`
+ * method (available in Chromium and WebKit) while providing a robust fallback to the
+ * standard `scrollIntoView` API for other browsers. It is designed to prevent jarring
+ * layout jumps by avoiding redundant scrolls if the element is already within the
+ * user's visible area.
+ *
+ * The function allows for flexible positioning, enabling you to either center the
+ * element within the viewport or use a minimal `"nearest"` alignment strategy to
+ * reduce visual noise during navigation or search-in-page operations.
+ *
+ * @example
+ * ```ts
+ * scrollIntoViewIfNeeded({
+ * element: document.querySelector("#target-element"),
+ * center: true
+ * });
+ * ```
+ */
+declare const scrollIntoViewIfNeeded: (params: ScrollIntoViewIfNeededParams) => void;
+
+export { type HTMLElementWithScrollIntoViewIfNeeded, type ScrollIntoViewIfNeededParams, scrollIntoViewIfNeeded };

package/dist/scroll-into-view-if-needed/index.js

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

package/dist/scroll-into-view-if-needed/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.5.0",
+  "version": "0.7.0",
   "description": "",
   "keywords": [],
   "homepage": "https://github.com/ZAHON/entry-ui/tree/main/packages/utilities#readme",