@entry-ui/utilities 0.5.0 → 0.6.0

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

@@ -10,6 +10,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 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
 //# 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.6.0",
   "description": "",
   "keywords": [],
   "homepage": "https://github.com/ZAHON/entry-ui/tree/main/packages/utilities#readme",