@vdegenne/highlight-manager 0.1.1

package/lib/index.d.ts

@@ -0,0 +1,65 @@
+interface Info {
+    elements: HTMLElement[];
+    highlightIndexStart: number;
+    highlightIndexEnd: number;
+    highlightElements: HTMLElement[];
+    /**
+     * First element of highlightElements if there is one
+     */
+    highlightElement: HTMLElement | undefined;
+    highlightContent: string | undefined;
+}
+interface Options {
+    css: string;
+    highlightTextColor: string;
+    /**
+     * @default true
+     */
+    loop: boolean;
+    /**
+     * A function for extra selection if selector is not enough
+     * and need a way to filter elements based on properties.
+     * Return false if you want to keep an element out of the bag.
+     */
+    atomicSelection: (element: HTMLElement, i: number) => boolean;
+    beforeHighlight: (() => void) | undefined;
+    onSelectionChange: ((info: Info) => void) | undefined;
+    /**
+     * By default the stylesheet for selection is applied to the main document.
+     * Which means won't highlight elements in shadow doms.
+     * You can target the element to give the stylesheet to.
+     * If the given element has no shadow dom, it will fail silently.
+     */
+    applyStyleSheetTo: Document | HTMLElement | ShadowRoot;
+    /**
+     * @default false
+     */
+    scrollWhenOffscreen: boolean;
+}
+export declare class HighLightManager {
+    #private;
+    protected selector: string;
+    constructor(selector: string, options?: Partial<Options>);
+    replaceCSS(css: string): void;
+    highlightWhenAvailable(index?: number, { checkSpeedMs, timeout, }?: {
+        checkSpeedMs?: number;
+        timeout?: number;
+    }): Promise<HTMLElement>;
+    cancelHighlightWhenAvailable(reason?: unknown): void;
+    getInfo(cache?: boolean): Info;
+    unhighlightAll(elements?: HTMLElement[], cache?: boolean): void;
+    highlightAll(cache?: boolean): void;
+    selectAll: (cache?: boolean) => void;
+    /**
+     * @returns {boolean} true if the highlight succeeded, false otherwise.
+     */
+    highlight(start: number, end?: number, unhighlightAll?: boolean, cache?: boolean): boolean;
+    previous(step?: number, cache?: boolean): void;
+    next(step?: number, cache?: boolean): void;
+    extendLeftHighlight(step?: number, cache?: boolean): void;
+    reduceLeftHighlight(step?: number, cache?: boolean): void;
+    extendRightHighlight(step?: number, cache?: boolean): void;
+    reduceRightHighlight(step?: number, cache?: boolean): void;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -0,0 +1,234 @@
+import { querySelectorAll } from 'html-vision';
+import { isInViewport, sleep } from './utils.js';
+const defaults = {
+    atomicSelection(_element) {
+        return true;
+    },
+    // css: 'background-color: #cddc39a1 !important; color: black !important',
+    // css: 'background-color: var(--md-sys-color-surface-container-highest) !important; color: var(--md-sys-color-on-surface) !important',
+    css: 'background-color: var(--md-sys-color-primary-container) !important; color: var(--md-sys-color-on-primary-container) !important',
+    // css: 'background-color: var(--md-sys-color-primary) !important; color: var(--md-sys-color-on-primary) !important',
+    // css: 'background-color: var(--md-sys-color-outline-variant) !important; color: var(--md-sys-color-on-surface) !important',
+    highlightTextColor: 'var(--md-sys-color-on-primary-container)',
+    loop: true,
+    beforeHighlight: undefined,
+    onSelectionChange: undefined,
+    applyStyleSheetTo: document,
+    scrollWhenOffscreen: false,
+};
+// Local array of all declared highlighters for id control.
+const highlighters = [];
+export class HighLightManager {
+    #cache;
+    #options;
+    #ss;
+    #id;
+    constructor(selector, options) {
+        this.selector = selector;
+        this.#cache = {
+            elements: [],
+            // highlightIndex: -1,
+            highlightIndexStart: -1,
+            highlightIndexEnd: -1,
+            // highlightElement: undefined,
+            highlightElements: [],
+            highlightElement: undefined,
+            highlightContent: undefined,
+        };
+        // alias
+        this.selectAll = this.highlightAll.bind(this);
+        this.#id = highlighters.push(this);
+        this.#options = { ...defaults, ...options };
+        /* stylesheet */
+        this.#ss = new CSSStyleSheet();
+        let applyTo; // element to apply stylesheet to
+        if (this.#options.applyStyleSheetTo === document.documentElement ||
+            !(this.#options.applyStyleSheetTo instanceof HTMLElement) ||
+            this.#options.applyStyleSheetTo.shadowRoot === null) {
+            applyTo = document;
+        }
+        else {
+            applyTo = this.#options.applyStyleSheetTo.shadowRoot;
+        }
+        applyTo.adoptedStyleSheets.push(this.#ss);
+        // this.#ss.replaceSync(`[highlight] {${css}}`);
+        this.replaceCSS(this.#options.css);
+    }
+    replaceCSS(css) {
+        this.#options.css = css;
+        this.#ss.replaceSync(`[highlight${this.#id}] {${css}} [highlight${this.#id}]:hover {${css}} [highlight${this.#id}] * {color: ${this.#options.highlightTextColor} !important;}`);
+    }
+    #highlightWhenAvailablePromiseWR;
+    highlightWhenAvailable(index = 0, { checkSpeedMs = 1000, timeout = 5000, } = {}) {
+        // cancel any existing run
+        this.cancelHighlightWhenAvailable('restarted');
+        const wr = Promise.withResolvers();
+        this.#highlightWhenAvailablePromiseWR = wr;
+        (async () => {
+            const start = Date.now();
+            while (this.#highlightWhenAvailablePromiseWR === wr) {
+                const els = querySelectorAll(this.selector);
+                const el = els[index];
+                if (el) {
+                    this.highlight(index, index, true, false);
+                    wr.resolve(el);
+                    this.#highlightWhenAvailablePromiseWR = undefined;
+                    return;
+                }
+                if (timeout > 0 && Date.now() - start >= timeout) {
+                    this.cancelHighlightWhenAvailable('timeout');
+                    return;
+                }
+                await sleep(checkSpeedMs);
+            }
+        })();
+        return wr.promise;
+    }
+    cancelHighlightWhenAvailable(reason = 'canceled') {
+        if (this.#highlightWhenAvailablePromiseWR) {
+            this.#highlightWhenAvailablePromiseWR.reject(reason);
+            this.#highlightWhenAvailablePromiseWR = undefined;
+        }
+    }
+    getInfo(cache = false) {
+        if (cache) {
+            return this.#cache;
+        }
+        // console.log(this.selector)
+        const elements = querySelectorAll(this.selector).filter((el, i) => this.#options.atomicSelection(el, i));
+        const highlightElements = elements.filter((el) => el.hasAttribute(`highlight${this.#id}`));
+        // const highlightIndexStart = elements.findIndex((el) =>
+        // 	el.hasAttribute('highlight'),
+        // );
+        if (!highlightElements || highlightElements.length === 0) {
+            throw Error("The highlighted element couldn't be found");
+        }
+        const highlightIndexStart = elements.indexOf(highlightElements[0]);
+        const highlightIndexEnd = elements.indexOf(highlightElements[highlightElements.length - 1]);
+        if (highlightElements.length === 1) {
+            // const highlightElement = elements[highlightIndex];
+        }
+        const highlightContent = highlightElements
+            // TODO: should prob change that ariaLabel (for lens into a customizable content getter)
+            .map((el) => el.ariaLabel || el.innerText?.trim() || '')
+            .join('');
+        // highlightElement?.innerText.trim();
+        return (this.#cache = {
+            elements,
+            // highlightIndex,
+            highlightIndexStart,
+            highlightIndexEnd,
+            highlightElements,
+            highlightElement: highlightElements[0],
+            highlightContent,
+        });
+    }
+    unhighlightAll(elements, cache = true) {
+        if (!elements) {
+            elements = this.getInfo(cache).elements;
+        }
+        elements.forEach((el) => el.removeAttribute(`highlight${this.#id}`));
+    }
+    highlightAll(cache = false) {
+        const { elements } = this.getInfo(cache);
+        this.highlight(0, elements.length - 1, false, cache);
+    }
+    /**
+     * @returns {boolean} true if the highlight succeeded, false otherwise.
+     */
+    highlight(start, end, unhighlightAll = true, cache = false) {
+        if (end === undefined) {
+            end = start;
+        }
+        if (start > end) {
+            return false;
+            // const tmp = start
+            // start = end
+            // end = tmp
+        }
+        const { elements, highlightIndexStart, highlightIndexEnd } = this.getInfo(cache);
+        // console.log(elements)
+        if (highlightIndexStart === start && highlightIndexEnd === end) {
+            return false;
+        }
+        // console.log(highlightIndexStart, highlightIndexEnd, start, end)
+        this.#options.beforeHighlight?.();
+        // playClick()
+        if (unhighlightAll) {
+            this.unhighlightAll(elements, cache);
+        }
+        const elementsToHighlight = elements.slice(start, end + 1);
+        if (elementsToHighlight.length === 0) {
+            return false;
+        }
+        if (this.#options.scrollWhenOffscreen ||
+            !isInViewport(elementsToHighlight[0])) {
+            elementsToHighlight[0]?.scrollIntoView({
+                behavior: 'smooth',
+                block: 'center',
+                inline: 'center',
+            });
+        }
+        elementsToHighlight.forEach((el) => el.setAttribute(`highlight${this.#id}`, ''));
+        // elements[index]?.setAttribute('highlight', '');
+        if (this.#options.onSelectionChange) {
+            this.#options.onSelectionChange(this.getInfo(false));
+        }
+        return true;
+    }
+    previous(step = 1, cache = false) {
+        const { elements, highlightIndexStart, highlightIndexEnd } = this.getInfo(cache);
+        const len = elements.length;
+        if (len === 0) {
+            this.highlight(-1, -1, true, cache);
+            return;
+        }
+        let previousIndex = highlightIndexStart !== highlightIndexEnd
+            ? highlightIndexStart
+            : this.#options.loop
+                ? (highlightIndexStart - step + len) % len
+                : Math.max(0, highlightIndexStart - step);
+        this.highlight(previousIndex, previousIndex, true, cache);
+    }
+    next(step = 1, cache = false) {
+        const { elements, highlightIndexStart, highlightIndexEnd } = this.getInfo(cache);
+        const len = elements.length;
+        if (len === 0) {
+            this.highlight(-1, -1, true, cache);
+            return;
+        }
+        let nextIndex = highlightIndexStart !== highlightIndexEnd
+            ? highlightIndexEnd
+            : this.#options.loop
+                ? (highlightIndexEnd + step) % len
+                : Math.min(len - 1, highlightIndexEnd + step);
+        this.highlight(nextIndex, nextIndex, true, cache);
+    }
+    extendLeftHighlight(step = 1, cache = false) {
+        // playClick();
+        const { highlightIndexStart, highlightIndexEnd } = this.getInfo(cache);
+        const newStart = Math.max(0, highlightIndexStart - step);
+        this.highlight(newStart, highlightIndexEnd, false, cache);
+    }
+    reduceLeftHighlight(step = 1, cache = false) {
+        // playClick();
+        const { elements, highlightIndexStart, highlightIndexEnd } = this.getInfo(cache);
+        // TODO: should prob change the min to end index
+        const newStart = Math.min(elements.length - 1, highlightIndexStart + step);
+        this.highlight(newStart, highlightIndexEnd, true, cache);
+    }
+    extendRightHighlight(step = 1, cache = false) {
+        // playClick();
+        const { elements, highlightIndexStart, highlightIndexEnd } = this.getInfo(cache);
+        const newEnd = Math.min(elements.length - 1, highlightIndexEnd + step);
+        this.highlight(highlightIndexStart, newEnd, false, cache);
+    }
+    reduceRightHighlight(step = 1, cache = false) {
+        // playClick();
+        const { highlightIndexStart, highlightIndexEnd } = this.getInfo(cache);
+        // TODO: should prob change the max to end index
+        const newEnd = Math.max(0, highlightIndexEnd - step);
+        this.highlight(highlightIndexStart, newEnd, true, cache);
+    }
+}
+//# sourceMappingURL=index.js.map

package/lib/utils.d.ts

@@ -0,0 +1,3 @@
+export declare function sleep(milli?: number): Promise<unknown>;
+export declare function isInViewport(el: Element): boolean;
+//# sourceMappingURL=utils.d.ts.map

package/lib/utils.js

@@ -0,0 +1,8 @@
+export function sleep(milli = 1000) {
+    return new Promise((r) => setTimeout(r, milli));
+}
+export function isInViewport(el) {
+    return (el.getBoundingClientRect().top >= 0 &&
+        el.getBoundingClientRect().bottom <= window.innerHeight);
+}
+//# sourceMappingURL=utils.js.map

package/package.json

@@ -0,0 +1,40 @@
+{
+	"name": "@vdegenne/highlight-manager",
+	"version": "0.1.1",
+	"description": "helper to navigate/highlight elements in a page based on a css selector",
+	"type": "module",
+	"exports": {
+		".": {
+			"import": "./lib/index.js",
+			"types": "./lib/index.d.ts"
+		}
+	},
+	"files": [
+		"lib/**",
+		"!lib/**/*.js.map",
+		"!lib/**/*.d.ts.map"
+	],
+	"scripts": {
+		"build": "wireit"
+	},
+	"wireit": {
+		"build": {
+			"command": "tsc --pretty",
+			"clean": "if-file-deleted",
+			"files": [
+				"./tsconfig.json",
+				"./src"
+			],
+			"output": [
+				"./lib"
+			]
+		}
+	},
+	"devDependencies": {
+		"typescript": "^6.0.3",
+		"wireit": "^0.14.12"
+	},
+	"dependencies": {
+		"html-vision": "^0.3.10"
+	}
+}