js-kompo-utils 1.0.0

package/tutorials/modules/HoverForcer.js

@@ -0,0 +1,250 @@
+/**
+ * Stylesheet scanning and inline :hover style injection.
+ *
+ * Forces :hover state on elements during tutorials by scanning all stylesheets
+ * for matching :hover rules and duplicating them with a special class selector.
+ */
+
+const HOVER_PROPS = [
+    'color', 'background-color', 'background', 'border-color',
+    'box-shadow', 'text-decoration', 'opacity', 'transform',
+    'outline', 'visibility', 'display',
+];
+
+const HOVER_CLASS_PATTERN = /hover[:\\]|vlOpenOnHover|hover-/;
+const FORCE_HOVER_CLASS = 'tutorial-force-hover';
+
+export class HoverForcer {
+    constructor() {
+        this.forcedElements = new Set();
+        this._hoverSheet = null;
+    }
+
+    /** @private */
+    _getHoverSheet() {
+        if (!this._hoverSheet) {
+            const styleEl = document.createElement('style');
+            styleEl.setAttribute('data-tutorial-hover', '');
+            document.head.appendChild(styleEl);
+            this._hoverSheet = styleEl.sheet;
+        }
+        return this._hoverSheet;
+    }
+
+    /**
+     * Force :hover styles onto an element.
+     * @param {HTMLElement} el
+     */
+    forceHover(el) {
+        this.removeHover(el);
+
+        const sheet = this._getHoverSheet();
+        const injectedRules = [];
+
+        try {
+            const sheets = document.styleSheets;
+            for (let i = 0; i < sheets.length; i++) {
+                let rules;
+                try {
+                    rules = sheets[i].cssRules || sheets[i].rules;
+                } catch {
+                    continue;
+                }
+                if (!rules) continue;
+
+                for (let j = 0; j < rules.length; j++) {
+                    const rule = rules[j];
+                    if (!rule.selectorText || !rule.selectorText.includes(':hover')) continue;
+
+                    const selectorParts = rule.selectorText.split(',');
+                    let matches = false;
+
+                    for (const rawPart of selectorParts) {
+                        const part = rawPart.trim();
+                        if (!part.includes(':hover')) continue;
+
+                        const hoverSegment = part.split(':hover')[0].trim();
+                        const lastSegment = hoverSegment.split(/[\s>+~]/).pop().trim();
+                        try {
+                            if (lastSegment && el.matches(lastSegment)) {
+                                matches = true;
+                                break;
+                            }
+                        } catch { /* invalid selector */ }
+
+                        const baseSelector = part.replace(/:hover/g, '');
+                        try {
+                            if (el.matches(baseSelector)) {
+                                matches = true;
+                                break;
+                            }
+                        } catch { /* invalid selector */ }
+                    }
+
+                    if (!matches) continue;
+
+                    const newSelector = rule.selectorText.replace(/:hover/g, '.' + FORCE_HOVER_CLASS);
+                    try {
+                        const idx = sheet.insertRule(
+                            `${newSelector} { ${rule.style.cssText} }`,
+                            sheet.cssRules.length,
+                        );
+                        injectedRules.push(idx);
+                    } catch { /* skip invalid rules */ }
+                }
+            }
+        } catch (e) {
+            console.warn('HoverForcer: forceHover failed', e);
+        }
+
+        el._tutorialHoverRules = injectedRules;
+        el.classList.add(FORCE_HOVER_CLASS);
+        this.forcedElements.add(el);
+    }
+
+    /**
+     * Remove forced hover styles from an element.
+     * @param {HTMLElement} el
+     */
+    removeHover(el) {
+        if (!el._tutorialHoverRules) return;
+
+        const sheet = this._getHoverSheet();
+        const indices = el._tutorialHoverRules.slice().sort((a, b) => b - a);
+        for (const idx of indices) {
+            try {
+                sheet.deleteRule(idx);
+            } catch { /* already removed */ }
+        }
+
+        delete el._tutorialHoverRules;
+        el.classList.remove(FORCE_HOVER_CLASS);
+        this.forcedElements.delete(el);
+    }
+
+    /**
+     * Check if an element has visible hover effects.
+     * @param {HTMLElement} el
+     * @returns {boolean}
+     */
+    elementHasHoverEffect(el) {
+        const normalStyle = window.getComputedStyle(el);
+        const normalValues = {};
+        for (const prop of HOVER_PROPS) {
+            normalValues[prop] = normalStyle.getPropertyValue(prop);
+        }
+
+        const testClass = `_tut_hover_test_${Date.now()}`;
+        const styleEl = document.createElement('style');
+        document.head.appendChild(styleEl);
+
+        let hasChange = false;
+
+        try {
+            const sheets = document.styleSheets;
+            for (let i = 0; i < sheets.length; i++) {
+                let rules;
+                try {
+                    rules = sheets[i].cssRules || sheets[i].rules;
+                } catch {
+                    continue;
+                }
+                if (!rules) continue;
+
+                for (let j = 0; j < rules.length; j++) {
+                    const rule = rules[j];
+                    if (!rule.selectorText || !rule.selectorText.includes(':hover')) continue;
+
+                    const baseSelector = rule.selectorText.replace(/:hover/g, '');
+                    try {
+                        if (!el.matches(baseSelector)) continue;
+                    } catch {
+                        continue;
+                    }
+
+                    const newSel = rule.selectorText.replace(/:hover/g, '.' + testClass);
+                    try {
+                        styleEl.sheet.insertRule(
+                            `${newSel}{${rule.style.cssText}}`,
+                            styleEl.sheet.cssRules.length,
+                        );
+                    } catch { /* skip invalid */ }
+                }
+            }
+
+            el.classList.add(testClass);
+            const hoverStyle = window.getComputedStyle(el);
+
+            for (const prop of HOVER_PROPS) {
+                if (hoverStyle.getPropertyValue(prop) !== normalValues[prop]) {
+                    hasChange = true;
+                    break;
+                }
+            }
+
+            el.classList.remove(testClass);
+        } catch { /* swallow errors */ }
+
+        document.head.removeChild(styleEl);
+
+        if (!hasChange && el.className && typeof el.className === 'string') {
+            if (HOVER_CLASS_PATTERN.test(el.className)) {
+                hasChange = true;
+            }
+        }
+
+        if (!hasChange && el.classList) {
+            for (const cls of el.classList) {
+                if (HOVER_CLASS_PATTERN.test(cls)) {
+                    hasChange = true;
+                    break;
+                }
+            }
+        }
+
+        return hasChange;
+    }
+
+    /**
+     * Find the closest ancestor (or self) with hover effects.
+     * @param {HTMLElement} el
+     * @returns {HTMLElement|null}
+     */
+    findHoverableParent(el) {
+        let current = el;
+        while (current && current !== document.body) {
+            if (this.elementHasHoverEffect(current)) return current;
+            current = current.parentElement;
+        }
+        return null;
+    }
+
+    /**
+     * Remove all forced hover styles and reset state.
+     */
+    clearAll() {
+        for (const el of this.forcedElements) {
+            if (el._tutorialHoverRules) {
+                const sheet = this._getHoverSheet();
+                const indices = el._tutorialHoverRules.slice().sort((a, b) => b - a);
+                for (const idx of indices) {
+                    try {
+                        sheet.deleteRule(idx);
+                    } catch { /* already removed */ }
+                }
+                delete el._tutorialHoverRules;
+            }
+            el.classList.remove(FORCE_HOVER_CLASS);
+            el.dispatchEvent(new MouseEvent('mouseleave', { bubbles: true }));
+        }
+        this.forcedElements.clear();
+
+        if (this._hoverSheet) {
+            const ownerNode = this._hoverSheet.ownerNode;
+            if (ownerNode && ownerNode.parentNode) {
+                ownerNode.parentNode.removeChild(ownerNode);
+            }
+            this._hoverSheet = null;
+        }
+    }
+}

package/tutorials/modules/Mobile.js

@@ -0,0 +1,148 @@
+/**
+ * Mobile detection and tab-dropdown adaptation.
+ */
+
+const MOBILE_BREAKPOINT = 600;
+
+export class Mobile {
+    /** @returns {boolean} */
+    isMobile() {
+        return window.innerWidth < MOBILE_BREAKPOINT;
+    }
+
+    /**
+     * Check whether a selector targets a hidden desktop tab and resolve mobile alternative.
+     * @param {string} selector
+     * @returns {object|null}
+     */
+    resolveMobileTab(selector) {
+        if (!this.isMobile()) return null;
+
+        const el = document.querySelector(selector);
+        if (!el) return null;
+
+        const isHiddenTab =
+            el.tagName === 'A' &&
+            el.getAttribute('role') === 'tab' &&
+            getComputedStyle(el).display === 'none';
+        if (!isHiddenTab) return null;
+
+        const tabsContainer = el.closest('.vlTabs');
+        if (!tabsContainer) return null;
+
+        const tabsId = tabsContainer.id || '';
+        const hash = tabsId.replace('responsive-tabs-', '');
+
+        let tabsSelectInput = hash
+            ? document.querySelector('input#tabs-select-' + hash)
+            : null;
+
+        if (!tabsSelectInput) {
+            const parent = tabsContainer.parentElement;
+            if (parent) {
+                tabsSelectInput = parent.querySelector('input[id^="tabs-select"]');
+            }
+        }
+        if (!tabsSelectInput) return null;
+
+        const dropdownWrapper = tabsSelectInput.closest('.vlInputWrapper');
+        if (!dropdownWrapper) return null;
+
+        const taggable = dropdownWrapper.querySelector('.vlTaggableInput');
+        if (!taggable) return null;
+
+        if (!dropdownWrapper.id) {
+            dropdownWrapper.id = 'tutorial-mobile-tab-' + hash;
+        }
+
+        const tabText = el.textContent.trim();
+        const allTabLinks = Array.from(tabsContainer.querySelectorAll('a[role="tab"]'));
+        const tabIndex = allTabLinks.indexOf(el);
+
+        return {
+            isMobileTab: true,
+            dropdown: dropdownWrapper,
+            taggable,
+            selector: '#' + dropdownWrapper.id,
+            optionText: tabText,
+            tabIndex,
+            tabsContainer,
+        };
+    }
+
+    /**
+     * Resolve hidden desktop tabs to mobile dropdown equivalents for a step.
+     * @param {object} step
+     * @returns {object}
+     */
+    resolveTabsForStep(step) {
+        if (!this.isMobile()) return step;
+
+        if (step.highlight) {
+            const hlCfg = step.highlight;
+            let hlSel = hlCfg.selector || null;
+            if (!hlSel && hlCfg.groups && hlCfg.groups.length) {
+                const grp = hlCfg.groups[0];
+                const els = grp.elements || grp;
+                if (els.length) hlSel = els[0];
+            }
+            if (hlSel) {
+                const mTab = this.resolveMobileTab(hlSel);
+                if (mTab) {
+                    step = JSON.parse(JSON.stringify(step));
+                    step.highlight = {
+                        groups: [{ elements: [mTab.selector] }],
+                        padding: (hlCfg.padding || 8),
+                        borderRadius: (hlCfg.borderRadius || 8),
+                    };
+                    this.selectMobileTab(mTab);
+                }
+            }
+        }
+
+        if (step.cursor && step.cursor.to) {
+            const cTab = this.resolveMobileTab(step.cursor.to);
+            if (cTab) {
+                step = typeof step._mobileCloned === 'undefined'
+                    ? JSON.parse(JSON.stringify(step))
+                    : step;
+                step._mobileCloned = true;
+                step.cursor.to = cTab.selector;
+                step.cursor.click = false;
+                step._mobileTabToSelect = cTab;
+            }
+        }
+
+        return step;
+    }
+
+    /**
+     * Click the mobile tab dropdown and select the matching option.
+     * @param {object} mobileTab
+     */
+    selectMobileTab(mobileTab) {
+        if (!mobileTab || !mobileTab.isMobileTab) return;
+
+        mobileTab.taggable.click();
+
+        setTimeout(() => {
+            const options = mobileTab.dropdown.querySelectorAll('.vlOption');
+            let clicked = false;
+
+            for (let i = 0; i < options.length; i++) {
+                if (options[i].textContent.trim() === mobileTab.optionText) {
+                    options[i].click();
+                    clicked = true;
+                    break;
+                }
+            }
+
+            if (!clicked) {
+                const vue = mobileTab.tabsContainer.__vue__;
+                if (vue && typeof vue.selectTab === 'function' && mobileTab.tabIndex >= 0) {
+                    vue.selectTab(mobileTab.tabIndex);
+                }
+            }
+        }, 200);
+    }
+}

package/tutorials/modules/Options.js

@@ -0,0 +1,98 @@
+import { gsap } from 'gsap';
+
+const STEP_TRANSITION_MS = 300;
+
+/**
+ * Renders option buttons inside a tutorial step's options row.
+ */
+export class Options {
+    constructor() {
+        /** @type {HTMLButtonElement[]} */
+        this.buttons = [];
+    }
+
+    /**
+     * Render option buttons into the container.
+     * @param {Array<object>} options
+     * @param {HTMLElement} container
+     * @param {object} callbacks - { goToStep, close, advanceClick, onTransition }
+     */
+    render(options, container, callbacks) {
+        this.destroy();
+
+        if (!container) return;
+
+        container.style.display = 'flex';
+        container.style.pointerEvents = 'none';
+
+        const totalOpts = options.length;
+        let renderedCount = 0;
+
+        options.forEach((opt, oi) => {
+            const btn = document.createElement('button');
+            btn.textContent = opt.label;
+            btn.className = 'tutorial-option-btn';
+
+            const hoverBg = opt.hoverColor || '#07499e';
+            const normalBg = opt.color || '#f0f4ff';
+            const normalColor = opt.textColor || '#07499e';
+
+            // Dynamic colors that depend on step config
+            btn.style.backgroundColor = normalBg;
+            btn.style.color = normalColor;
+            btn.style.border = '2px solid ' + (opt.borderColor || '#07499e');
+
+            const setColors = (bg, color) => {
+                btn.style.backgroundColor = bg;
+                btn.style.color = color;
+            };
+            btn.addEventListener('mouseenter', () => setColors(hoverBg, '#ffffff'));
+            btn.addEventListener('mouseleave', () => setColors(normalBg, normalColor));
+            btn.addEventListener('touchstart', () => setColors(hoverBg, '#ffffff'), { passive: true });
+            btn.addEventListener('touchend', () => setColors(normalBg, normalColor), { passive: true });
+
+            btn.addEventListener('click', () => {
+                if (opt.done) {
+                    callbacks.close();
+                } else if (opt.redirect) {
+                    let url = opt.redirect;
+                    if (opt.startTutorial !== undefined && opt.startTutorial !== false) {
+                        const fromStep = typeof opt.startTutorial === 'number' ? opt.startTutorial : 0;
+                        const name = typeof opt.startTutorial === 'string' ? opt.startTutorial : '';
+                        const sep = url.includes('?') ? '&' : '?';
+                        url += `${sep}tutorial=${encodeURIComponent(name)}&fromStep=${fromStep}`;
+                    }
+                    window.location.href = url;
+                } else if (opt.goToStep !== undefined) {
+                    callbacks.onTransition?.();
+                    setTimeout(() => callbacks.goToStep(opt.goToStep), STEP_TRANSITION_MS);
+                } else {
+                    callbacks.advanceClick();
+                }
+            });
+
+            container.appendChild(btn);
+            this.buttons.push(btn);
+
+            gsap.to(btn, {
+                opacity: 1,
+                y: 0,
+                duration: 0.3,
+                delay: 0.1 * (oi + 1),
+                ease: 'power2.out',
+                onComplete: () => {
+                    btn.style.pointerEvents = 'auto';
+                    renderedCount++;
+                    if (renderedCount === totalOpts) {
+                        container.style.pointerEvents = 'auto';
+                    }
+                },
+            });
+        });
+    }
+
+    destroy() {
+        this.buttons.forEach((btn) => btn.remove());
+        this.buttons = [];
+    }
+}

package/tutorials/modules/Overlay.js

@@ -0,0 +1,142 @@
+/**
+ * Z-index constants shared across all tutorial modules.
+ */
+const Z = {
+    OVERLAY: 9997,
+    HIGHLIGHT: 9998,
+    CURSOR: 10000,
+    PULSE: 10001,
+    CONTAINER: 10002,
+};
+
+export { Z };
+
+/**
+ * Manages the full-screen overlay, click blocking, and mobile peek button.
+ */
+export class Overlay {
+    constructor(engine) {
+        this.engine = engine;
+        this.el = null;
+        this.peekBtn = null;
+        this.peekHidden = false;
+        this._peekClickHandler = null;
+        this._peekTouchHandler = null;
+        this._savedOverflow = '';
+    }
+
+    /**
+     * Build overlay and peek button, append to document.body.
+     * Safe to call multiple times — cleans up previous DOM first.
+     */
+    create() {
+        if (this.el) this.destroy();
+
+        this._savedOverflow = document.body.style.overflow;
+
+        this.el = document.createElement('div');
+        this.el.id = 'tutorial-overlay';
+        this.el.className = 'tutorial-overlay';
+        this.el.setAttribute('role', 'dialog');
+        this.el.setAttribute('aria-modal', 'true');
+        this.el.setAttribute('aria-label', 'Tutorial');
+        this.el.style.backgroundColor = 'rgba(0,0,0,0.5)'; // Default dark, setMode() toggles
+
+        document.body.appendChild(this.el);
+        document.body.style.overflow = 'hidden';
+
+        // Mobile peek button -- hides avatar+bubble so user can see behind overlay
+        this.peekBtn = document.createElement('button');
+        this.peekBtn.textContent = '\uD83D\uDC41';
+        this.peekBtn.className = 'tutorial-peek-btn';
+
+        this._peekClickHandler = (e) => {
+            e.stopPropagation();
+            this.peekHidden = !this.peekHidden;
+
+            const container = this.engine.getContainer?.();
+            if (container) {
+                container.style.display = this.peekHidden ? 'none' : 'flex';
+            }
+
+            if (this.peekHidden) {
+                this.el.style.backgroundColor = 'transparent';
+            } else {
+                const step = this.engine.getCurrentStep?.();
+                const hasHighlight = this.engine.hasActiveHighlight?.();
+                const showOverlay = step ? (step.overlay !== false && !hasHighlight) : true;
+                this.el.style.backgroundColor = showOverlay
+                    ? 'rgba(0,0,0,0.5)'
+                    : 'transparent';
+            }
+
+            this.peekBtn.style.opacity = this.peekHidden ? '0.6' : '1';
+        };
+
+        this._peekTouchHandler = (e) => {
+            e.stopPropagation();
+        };
+
+        this.peekBtn.addEventListener('click', this._peekClickHandler);
+        this.peekBtn.addEventListener('touchstart', this._peekTouchHandler, { passive: true });
+        document.body.appendChild(this.peekBtn);
+    }
+
+    /**
+     * Toggle the overlay background between dimmed and transparent.
+     * @param {'dimmed'|'transparent'} mode
+     */
+    setMode(mode) {
+        if (!this.el) return;
+        this.el.style.backgroundColor = mode === 'dimmed'
+            ? 'rgba(0,0,0,0.5)'
+            : 'transparent';
+    }
+
+    /**
+     * Show or hide the mobile peek button.
+     * @param {boolean} show
+     */
+    showPeekButton(show) {
+        if (!this.peekBtn) return;
+        this.peekBtn.style.display = show ? 'flex' : 'none';
+    }
+
+    /**
+     * Reset peek state (un-hides the container if it was peeked).
+     */
+    resetPeek() {
+        if (!this.peekHidden) return;
+        this.peekHidden = false;
+        const container = this.engine.getContainer?.();
+        if (container) {
+            container.style.display = 'flex';
+        }
+        if (this.peekBtn) {
+            this.peekBtn.style.opacity = '1';
+        }
+    }
+
+    /**
+     * Remove overlay and peek button, restore body overflow, clean up listeners.
+     */
+    destroy() {
+        if (this.peekBtn) {
+            this.peekBtn.removeEventListener('click', this._peekClickHandler);
+            this.peekBtn.removeEventListener('touchstart', this._peekTouchHandler);
+            this.peekBtn.remove();
+            this.peekBtn = null;
+        }
+
+        if (this.el) {
+            this.el.remove();
+            this.el = null;
+        }
+
+        document.body.style.overflow = this._savedOverflow;
+
+        this._peekClickHandler = null;
+        this._peekTouchHandler = null;
+        this.peekHidden = false;
+    }
+}

package/tutorials/modules/Scroll.js

@@ -0,0 +1,37 @@
+import { gsap } from 'gsap';
+
+/**
+ * Scroll helper: scrolls elements into view and scrolls content within containers.
+ */
+export class Scroll {
+    /**
+     * @param {string} selector - CSS selector for the target element
+     */
+    scrollTo(selector) {
+        const el = document.querySelector(selector);
+        if (!el) return;
+        el.scrollIntoView({ behavior: 'smooth', block: 'center' });
+    }
+
+    /**
+     * Animate the scroll position inside a scrollable container.
+     * @param {object} opts
+     * @param {string} opts.selector
+     * @param {number} [opts.to]
+     * @param {number} [opts.by]
+     * @param {number} [opts.duration=1]
+     */
+    scrollInside({ selector, to, by, duration = 1 }) {
+        const container = document.querySelector(selector);
+        if (!container) return;
+
+        const amount = to !== undefined ? to : (by || 300);
+        const target = to !== undefined ? amount : container.scrollTop + amount;
+
+        gsap.to(container, {
+            scrollTop: target,
+            duration,
+            ease: 'power2.inOut',
+        });
+    }
+}