@vdegenne/highlight-manager 0.1.6 → 0.1.8

package/lib/index.d.ts

@@ -1,3 +1,4 @@
+import { IsInViewportPartCheck } from './utils.js';
 interface Info {
     elements: HTMLElement[];
     highlightIndexStart: number;
@@ -9,6 +10,20 @@ interface Info {
     highlightElement: HTMLElement | undefined;
     highlightContent: string | undefined;
 }
+interface ScrollStrategy {
+    /**
+     * @default 'center'
+     */
+    whenWhatPartIsHidden: IsInViewportPartCheck;
+    /**
+     * @default 'smooth'
+     */
+    behavior: ScrollBehavior;
+    /**
+     * @default 'start'
+     */
+    logicalPosition: ScrollLogicalPosition;
+}
 interface Options {
     css: string;
     highlightTextColor: string;
@@ -32,9 +47,9 @@ interface Options {
      */
     applyStyleSheetTo: Document | HTMLElement | ShadowRoot;
     /**
-     * @default false
+     * @default undefined
      */
-    scrollWhenOffscreen: boolean;
+    scrollStrategy: ScrollStrategy | undefined;
     /**
      * If true, will select the next visible candidate if the highlight is offscreen.
      *
@@ -43,6 +58,9 @@ interface Options {
     fastTravel: boolean;
 }
 export declare function setGlobalBeforeHighlight(fct: () => void): void;
+interface HighlightOptions {
+    scrollStrategy: ScrollStrategy | undefined;
+}
 export declare class HighLightManager {
     #private;
     protected selector: string;
@@ -60,7 +78,7 @@ export declare class HighLightManager {
     /**
      * @returns {boolean} true if the highlight succeeded, false otherwise.
      */
-    highlight(start: number, end?: number, unhighlightAll?: boolean, cache?: boolean): boolean;
+    highlight(start: number, end?: number, unhighlightAll?: boolean, cache?: boolean, options?: HighlightOptions): boolean;
     previous(step?: number, cache?: boolean): void;
     next(step?: number, cache?: boolean): void;
     extendLeftHighlight(step?: number, cache?: boolean): void;

package/lib/index.js

@@ -1,5 +1,10 @@
 import { querySelectorAll } from 'html-vision';
 import { isInViewport, sleep } from './utils.js';
+const scrollStrategyDefaults = {
+    whenWhatPartIsHidden: 'center',
+    behavior: 'smooth',
+    logicalPosition: 'start',
+};
 const defaults = {
     atomicSelection(_element) {
         return true;
@@ -14,7 +19,7 @@ const defaults = {
     beforeHighlight: undefined,
     onSelectionChange: undefined,
     applyStyleSheetTo: document,
-    scrollWhenOffscreen: false,
+    scrollStrategy: undefined,
     fastTravel: false,
 };
 // Local array of all declared highlighters for id control.
@@ -150,7 +155,7 @@ export class HighLightManager {
     /**
      * @returns {boolean} true if the highlight succeeded, false otherwise.
      */
-    highlight(start, end, unhighlightAll = true, cache = false) {
+    highlight(start, end, unhighlightAll = true, cache = false, options) {
         if (end === undefined) {
             end = start;
         }
@@ -166,6 +171,13 @@ export class HighLightManager {
             return false;
         }
         // console.log(highlightIndexStart, highlightIndexEnd, start, end)
+        const _options = {
+            scrollStrategy: {
+                ...scrollStrategyDefaults,
+                ...this.#options.scrollStrategy,
+                ...options?.scrollStrategy,
+            },
+        };
         globalBeforeHighlight?.();
         this.#options.beforeHighlight?.();
         // playClick()
@@ -176,12 +188,12 @@ export class HighLightManager {
         if (elementsToHighlight.length === 0) {
             return false;
         }
-        if (this.#options.scrollWhenOffscreen &&
-            !isInViewport(elementsToHighlight[0])) {
+        if (_options.scrollStrategy &&
+            !isInViewport(elementsToHighlight[0], _options.scrollStrategy.whenWhatPartIsHidden)) {
             elementsToHighlight[0]?.scrollIntoView({
-                behavior: 'smooth',
-                block: 'center',
-                inline: 'center',
+                behavior: _options.scrollStrategy.behavior,
+                block: _options.scrollStrategy.logicalPosition,
+                inline: _options.scrollStrategy.logicalPosition,
             });
         }
         elementsToHighlight.forEach((el) => el.setAttribute(`highlight${this.#id}`, ''));

package/lib/utils.d.ts

@@ -1,3 +1,4 @@
 export declare function sleep(milli?: number): Promise<unknown>;
-export declare function isInViewport(el: HTMLElement): boolean;
+export type IsInViewportPartCheck = 'top' | 'center' | 'bounding-rect' | 'bottom';
+export declare function isInViewport(el: HTMLElement, partCheck?: IsInViewportPartCheck): boolean;
 //# sourceMappingURL=utils.d.ts.map

package/lib/utils.js

@@ -1,19 +1,29 @@
 export function sleep(milli = 1000) {
     return new Promise((r) => setTimeout(r, milli));
 }
-// export function isInViewport(el: Element) {
-// 	return (
-// 		el.getBoundingClientRect().top >= 0 &&
-// 		el.getBoundingClientRect().bottom <= window.innerHeight
-// 	)
-// }
-export function isInViewport(el) {
+export function isInViewport(el, partCheck = 'center') {
     const rect = el.getBoundingClientRect();
     const viewHeight = window.innerHeight || document.documentElement.clientHeight;
     const viewWidth = window.innerWidth || document.documentElement.clientWidth;
-    return (rect.bottom > 0 &&
-        rect.right > 0 &&
-        rect.top < viewHeight &&
-        rect.left < viewWidth);
+    switch (partCheck) {
+        case 'top':
+            return rect.top >= 0 && rect.top <= viewHeight;
+        case 'bottom':
+            return rect.bottom >= 0 && rect.bottom <= viewHeight;
+        case 'center': {
+            const centerY = rect.top + rect.height / 2;
+            const centerX = rect.left + rect.width / 2;
+            return (centerY >= 0 &&
+                centerY <= viewHeight &&
+                centerX >= 0 &&
+                centerX <= viewWidth);
+        }
+        case 'bounding-rect':
+        default:
+            return (rect.bottom > 0 &&
+                rect.right > 0 &&
+                rect.top < viewHeight &&
+                rect.left < viewWidth);
+    }
 }
 //# sourceMappingURL=utils.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vdegenne/highlight-manager",
-	"version": "0.1.6",
+	"version": "0.1.8",
 	"description": "helper to navigate/highlight elements in a page based on a css selector",
 	"type": "module",
 	"exports": {