@vdegenne/highlight-manager 0.1.7 → 0.1.9

package/lib/index.d.ts

@@ -1,3 +1,4 @@
+import { IsInViewportPartCheck } from './utils.js';
 interface Info {
     elements: HTMLElement[];
     highlightIndexStart: number;
@@ -9,7 +10,20 @@ interface Info {
     highlightElement: HTMLElement | undefined;
     highlightContent: string | undefined;
 }
-type ScrollWhenOffscreenOption = 'never' | 'bounding-rect' | 'top';
+interface ScrollStrategy {
+    /**
+     * @default 'center'
+     */
+    whenWhatPartIsHidden: IsInViewportPartCheck;
+    /**
+     * @default 'smooth'
+     */
+    behavior: ScrollBehavior;
+    /**
+     * @default 'start'
+     */
+    logicalPosition: ScrollLogicalPosition;
+}
 interface Options {
     css: string;
     highlightTextColor: string;
@@ -33,9 +47,9 @@ interface Options {
      */
     applyStyleSheetTo: Document | HTMLElement | ShadowRoot;
     /**
-     * @default 'none'
+     * @default undefined
      */
-    scrollWhenOffscreen: ScrollWhenOffscreenOption;
+    scrollStrategy: Partial<ScrollStrategy> | undefined;
     /**
      * If true, will select the next visible candidate if the highlight is offscreen.
      *
@@ -45,7 +59,7 @@ interface Options {
 }
 export declare function setGlobalBeforeHighlight(fct: () => void): void;
 interface HighlightOptions {
-    scrollWhenOffscreen: ScrollWhenOffscreenOption;
+    scrollStrategy: Partial<ScrollStrategy> | undefined;
 }
 export declare class HighLightManager {
     #private;
@@ -64,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, options?: HighlightOptions): boolean;
+    highlight(start: number, end?: number, unhighlightAll?: boolean, cache?: boolean, options?: Partial<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: 'never',
+    scrollStrategy: undefined,
     fastTravel: false,
 };
 // Local array of all declared highlighters for id control.
@@ -75,9 +80,7 @@ export class HighLightManager {
                 const els = querySelectorAll(this.selector);
                 const el = els[index];
                 if (el) {
-                    this.highlight(index, index, true, false, {
-                        scrollWhenOffscreen: 'never',
-                    });
+                    this.highlight(index, index, true, false);
                     wr.resolve(el);
                     this.#highlightWhenAvailablePromiseWR = undefined;
                     return;
@@ -152,7 +155,7 @@ export class HighLightManager {
     /**
      * @returns {boolean} true if the highlight succeeded, false otherwise.
      */
-    highlight(start, end, unhighlightAll = true, cache = false, options) {
+    highlight(start, end, unhighlightAll = true, cache = false, options = {}) {
         if (end === undefined) {
             end = start;
         }
@@ -169,7 +172,13 @@ export class HighLightManager {
         }
         // console.log(highlightIndexStart, highlightIndexEnd, start, end)
         const _options = {
-            scrollWhenOffscreen: options?.scrollWhenOffscreen ?? this.#options.scrollWhenOffscreen,
+            scrollStrategy: options?.scrollStrategy || this.#options.scrollStrategy
+                ? {
+                    ...scrollStrategyDefaults,
+                    ...this.#options.scrollStrategy,
+                    ...options?.scrollStrategy,
+                }
+                : undefined,
         };
         globalBeforeHighlight?.();
         this.#options.beforeHighlight?.();
@@ -181,12 +190,12 @@ export class HighLightManager {
         if (elementsToHighlight.length === 0) {
             return false;
         }
-        if (_options.scrollWhenOffscreen !== 'never' &&
-            !isInViewport(elementsToHighlight[0], _options.scrollWhenOffscreen === 'top')) {
+        if (_options.scrollStrategy &&
+            !isInViewport(elementsToHighlight[0], _options.scrollStrategy.whenWhatPartIsHidden)) {
             elementsToHighlight[0]?.scrollIntoView({
-                behavior: 'smooth',
-                block: _options.scrollWhenOffscreen === 'top' ? 'start' : 'center',
-                inline: _options.scrollWhenOffscreen === 'top' ? 'start' : '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, onlyTop?: boolean): 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,22 +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, onlyTop = false) {
+export function isInViewport(el, partCheck = 'center') {
     const rect = el.getBoundingClientRect();
     const viewHeight = window.innerHeight || document.documentElement.clientHeight;
     const viewWidth = window.innerWidth || document.documentElement.clientWidth;
-    if (onlyTop) {
-        return rect.top >= 0 && rect.top <= viewHeight;
+    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);
     }
-    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.7",
+	"version": "0.1.9",
 	"description": "helper to navigate/highlight elements in a page based on a css selector",
 	"type": "module",
 	"exports": {