js-kompo-utils 1.0.0

package/tutorials/TutorialEngine.js

@@ -0,0 +1,448 @@
+import { TutorialConfig } from './TutorialConfig.js';
+import { Overlay } from './modules/Overlay.js';
+import { Avatar } from './modules/Avatar.js';
+import { Bubble } from './modules/Bubble.js';
+import { Typewriter } from './modules/Typewriter.js';
+import { Cursor } from './modules/Cursor.js';
+import { Highlight } from './modules/Highlight.js';
+import { HoverForcer } from './modules/HoverForcer.js';
+import { Scroll } from './modules/Scroll.js';
+import { Options } from './modules/Options.js';
+import { AutoNext } from './modules/AutoNext.js';
+import { Mobile } from './modules/Mobile.js';
+
+
+const STEP_TRANSITION_MS = 300;
+
+/**
+ * Main tutorial orchestrator. Delegates DOM building, positioning, and layout
+ * to dedicated modules.
+ */
+export class TutorialEngine {
+    static cache = new Map();
+
+    constructor(config = {}) {
+        this.config = new TutorialConfig(config);
+        this.overlay = new Overlay(this);
+        this.avatar = new Avatar(this);
+        this.bubble = new Bubble(this);
+        this.typewriter = new Typewriter(this);
+        this.cursor = new Cursor(this);
+        this.highlight = new Highlight(this);
+        this.hoverForcer = new HoverForcer();
+        this.scroll = new Scroll();
+        this.options = new Options();
+        this.autoNext = new AutoNext();
+        this.mobile = new Mobile();
+
+        this.steps = [];
+        this.currentStep = 0;
+        this._lastDirection = 1;
+        this._isAutoAdvancing = false;
+        this._onReadyCallbacks = [];
+        this._readyContext = null;
+        this._orientationHandler = null;
+        this._resizeHandler = null;
+        this._running = false;
+        this._startAborted = false;
+        this._startGeneration = 0;
+        this._hasActiveHighlight = false;
+    }
+
+    static async preload(tutorialName) {
+        if (TutorialEngine.cache.has(tutorialName)) {
+            return TutorialEngine.cache.get(tutorialName);
+        }
+        const response = await fetch(`/api/tutorials/${tutorialName}`);
+        const data = await response.json();
+        TutorialEngine.cache.set(tutorialName, data);
+        return data;
+    }
+
+
+    // ─── Interface methods for modules ─────────────────────────────────
+
+    getContainer() { return this.avatar.container; }
+    getCurrentStep() { return this.steps[this.currentStep]; }
+    hasActiveHighlight() { return this._hasActiveHighlight; }
+    isMobile() { return this.mobile.isMobile(); }
+    forceHover(el) { this.hoverForcer.forceHover(el); }
+
+    previewStep(index) {
+        this._showStep(index);
+    }
+
+    // ─── Public API ────────────────────────────────────────────────────
+
+    /**
+     * Start the tutorial.
+     *
+     * @param {string|Array} tutorialNameOrSteps - Tutorial name (fetched from API) or step array
+     * @param {number|object} [startStepOrOptions=0] - Start step index, or config options when passing step array
+     */
+    async start(tutorialNameOrSteps, startStepOrOptions = 0) {
+        // Cancel any in-flight start and clean up existing tutorial
+        this._startAborted = true;
+        if (this._running) {
+            this._close();
+        }
+        this._running = true;
+        this._startAborted = false;
+        this._startGeneration++;
+        const gen = this._startGeneration;
+
+        if (Array.isArray(tutorialNameOrSteps)) {
+            this.steps = tutorialNameOrSteps;
+            if (typeof startStepOrOptions === 'object') {
+                this.config = new TutorialConfig(startStepOrOptions);
+            }
+        } else {
+            let data = TutorialEngine.cache.get(tutorialNameOrSteps);
+            if (!data) {
+                const response = await fetch(`/api/tutorials/${tutorialNameOrSteps}`);
+                if (this._startAborted) return;
+                data = await response.json();
+                if (this._startAborted) return;
+                TutorialEngine.cache.set(tutorialNameOrSteps, data);
+            }
+            this.steps = data.steps;
+            if (data.options) {
+                this.config = new TutorialConfig(data.options);
+            }
+        }
+
+        let startFrom = typeof startStepOrOptions === 'number' ? startStepOrOptions : 0;
+        startFrom = startFrom || this.config.get('fromStep') || 0;
+
+        const avatarSrc = await this.avatar.preloadImage(this.config.get('avatar'));
+        if (this._startAborted) return;
+
+        this._buildDOM(avatarSrc);
+
+        requestAnimationFrame(() => {
+            if (gen !== this._startGeneration) return;
+            this._showStep(startFrom);
+        });
+
+        this._readyContext = {
+            overlay: this.overlay.el,
+            container: this.avatar.container,
+            steps: this.steps,
+            showStep: (i) => this._showStep(i),
+            activeCursor: () => this.cursor,
+            activeHighlight: () => this.highlight,
+            actionBtn: this.bubble.actionBtn,
+            bubble: this.bubble.getElement(),
+            textEl: this.bubble.getTextElement(),
+            optionsRow: this.bubble.getOptionsContainer(),
+            currentStep: () => this.currentStep,
+            opts: this.config.options,
+        };
+        for (const cb of this._onReadyCallbacks) { cb(this._readyContext); }
+    }
+
+    onReady(cb) {
+        this._onReadyCallbacks.push(cb);
+        if (this._readyContext) cb(this._readyContext);
+    }
+
+    // ─── Internal: DOM Construction ────────────────────────────────────
+
+    _buildDOM(avatarSrc) {
+        const opts = this.config.options;
+
+        this.overlay.create();
+        this.avatar.create(opts, avatarSrc);
+        this.bubble.create(opts);
+
+        // All tutorial elements are direct children of body with fixed positioning.
+        // This ensures floating-ui viewport coordinates map 1:1 to element position.
+        if (this.avatar.container) {
+            document.body.appendChild(this.avatar.container);
+        }
+        document.body.appendChild(this.bubble.getElement());
+
+        this._wireButtons();
+
+        this._orientationHandler = () => {
+            setTimeout(() => {
+                const step = this.steps[this.currentStep];
+                if (step) this._positionForStep(step);
+            }, 300);
+        };
+        this._resizeHandler = () => {
+            setTimeout(() => {
+                const step = this.steps[this.currentStep];
+                if (step) this._positionForStep(step);
+            }, 100);
+        };
+        window.addEventListener('orientationchange', this._orientationHandler);
+        window.addEventListener('resize', this._resizeHandler);
+    }
+
+    _wireButtons() {
+        if (this.bubble.actionBtn) {
+            this.bubble.actionBtn.addEventListener('click', () => { this._advance(); });
+        }
+
+        if (this.bubble.backBtn) {
+            this.bubble.backBtn.addEventListener('click', () => {
+                const step = this.steps[this.currentStep];
+                const target = (typeof step.showBack === 'number') ? step.showBack : this.currentStep - 1;
+                if (target >= 0) {
+                    this._lastDirection = -1;
+                    this.autoNext.clear();
+                    this._cleanupAnimations();
+                    this.bubble.hide();
+                    setTimeout(() => { this._showStep(target); }, STEP_TRANSITION_MS);
+                }
+            });
+        }
+
+        if (this.bubble.pauseBtn) {
+            this.bubble.pauseBtn.addEventListener('click', () => {
+                if (this.autoNext.paused) {
+                    this.autoNext.resume(() => {
+                        this._isAutoAdvancing = true;
+                        if (this.bubble.actionBtn) this.bubble.actionBtn.click();
+                    });
+                    this.bubble.pauseBtn.textContent = '\u275A\u275A';
+                    this.bubble.pauseBtn.setAttribute('aria-label', 'Pause');
+                } else {
+                    this.autoNext.pause();
+                    this.bubble.pauseBtn.textContent = '\u25B6';
+                    this.bubble.pauseBtn.setAttribute('aria-label', 'Resume');
+                }
+            });
+        }
+    }
+
+    // ─── Internal: Step Orchestration ──────────────────────────────────
+
+    async _showStep(index) {
+        let step = this.steps[index];
+        if (!step) return;
+        this.currentStep = index;
+
+        const isLast = index === this.steps.length - 1;
+        const devMode = this.config.get('devMode');
+
+        if (step.showIf) {
+            const sel = typeof step.showIf === 'string' ? step.showIf : step.showIf.selector;
+            if (sel && !document.querySelector(sel)) {
+                const nextIdx = index + this._lastDirection;
+                if (nextIdx >= 0 && nextIdx < this.steps.length) this._showStep(nextIdx);
+                return;
+            }
+        }
+
+        document.dispatchEvent(new CustomEvent('tutorial-step-change', { detail: { index } }));
+
+        this.autoNext.clear();
+        if (this.bubble.pauseBtn) this.bubble.pauseBtn.style.display = 'none';
+        this._cleanupAnimations();
+
+        if (step.scrollTo) this.scroll.scrollTo(step.scrollTo);
+        if (step.scrollInside) this.scroll.scrollInside(step.scrollInside);
+
+        if (step.silentClick && !this._isAutoAdvancing) {
+            if (!devMode) {
+                const silentEl = document.querySelector(step.silentClick);
+                if (silentEl && typeof silentEl.click === 'function') silentEl.click();
+            }
+            if (!isLast) this._showStep(this.currentStep + 1);
+            return;
+        }
+        this._isAutoAdvancing = false;
+
+        // When highlights are active, overlay stays dimmed until SVG is built.
+        // Highlight._build() will switch overlay to transparent once the SVG is in DOM.
+        this._hasActiveHighlight = !!step.highlight;
+        if (!this._hasActiveHighlight) {
+            this.overlay.setMode(step.overlay !== false ? 'dimmed' : 'transparent');
+        }
+        if (this.overlay.el) {
+            const blockClicks = (step.overlay !== false && !this._hasActiveHighlight) || step.clearOverlay;
+            this.overlay.el.style.pointerEvents = blockClicks ? 'auto' : 'none';
+        }
+        if (this.avatar.container) this.avatar.container.style.pointerEvents = 'auto';
+
+        this.bubble.setChatMode(!!step.chatMode, {
+            img: this.avatar.img,
+            videoEl: this.avatar.videoEl,
+        });
+
+        this.bubble.clearStepContent();
+        this.bubble.configureButtons({
+            isLast,
+            nextLabel: this.config.get('nextLabel'),
+            doneLabel: this.config.get('doneLabel'),
+            hasOptions: !!step.options,
+            showBack: step.showBack,
+        });
+
+        step = this.mobile.resolveTabsForStep(step);
+
+        let highlightBottom = false;
+        if (step.highlight) {
+            const result = this.highlight.scrollToElements(step, this.isMobile());
+            highlightBottom = result.highlightBottom;
+        }
+
+        try {
+            await this._positionForStep(step, highlightBottom);
+        } catch (e) {
+            console.warn('Tutorial: positioning failed', e);
+        }
+        this.bubble.show();
+
+        this.overlay.resetPeek();
+        if (this.avatar.container) this.avatar.container.style.display = 'flex';
+        this.overlay.showPeekButton(this.isMobile());
+
+        if (step.hover) {
+            const hoverSelectors = Array.isArray(step.hover) ? step.hover : [step.hover];
+            for (const sel of hoverSelectors) {
+                const el = document.querySelector(sel);
+                if (el) {
+                    const target = this.hoverForcer.findHoverableParent(el) || el;
+                    this.hoverForcer.forceHover(target);
+                    target.dispatchEvent(new MouseEvent('mouseenter', { bubbles: true }));
+                    target.dispatchEvent(new MouseEvent('mouseover', { bubbles: true }));
+                }
+            }
+        }
+
+        if (step.highlight) {
+            this.highlight.create(step.highlight);
+        }
+
+        setTimeout(() => {
+            const twSpeed = devMode ? 0 : this.config.get('typewriteSpeed');
+            this.typewriter.type(this.bubble.getTextElement(), step.html || '', twSpeed, () => {
+                this.bubble.revealButtons();
+                this._handlePostTyping(step, isLast);
+            });
+        }, STEP_TRANSITION_MS);
+    }
+
+    _handlePostTyping(step, isLast) {
+        const devMode = this.config.get('devMode');
+
+        if (step.options && step.options.length) {
+            this.options.render(step.options, this.bubble.getOptionsContainer(), {
+                goToStep: (i) => this._showStep(i),
+                close: () => this._close(),
+                redirect: (url) => { window.location.href = url; },
+                onTransition: () => this.bubble.hide(),
+                advanceClick: () => this._advance(),
+            });
+        }
+
+        if (step.cursor && !step.afterAnimation) {
+            const mobileTabCb = step._mobileTabToSelect
+                ? () => this.mobile.selectMobileTab(step._mobileTabToSelect)
+                : null;
+            this.cursor.launch(step, this.overlay.el, mobileTabCb);
+        }
+
+        if (step.autoNext && !isLast) {
+            const seconds = (typeof step.autoNext === 'number') ? step.autoNext : 3;
+            if (this.bubble.pauseBtn) {
+                this.bubble.pauseBtn.style.display = '';
+                this.bubble.pauseBtn.textContent = '\u275A\u275A';
+            }
+
+            this.autoNext.start(seconds, this.bubble.getElement(), () => {
+                this._isAutoAdvancing = true;
+                if (this.bubble.actionBtn) this.bubble.actionBtn.click();
+            });
+
+            if (devMode) {
+                this.autoNext.pause();
+                if (this.bubble.pauseBtn) {
+                    this.bubble.pauseBtn.textContent = '\u25B6';
+                    this.bubble.pauseBtn.setAttribute('aria-label', 'Resume');
+                }
+            }
+        }
+
+        if (step.afterAnimation && !isLast) {
+            if (this.bubble.actionBtn) this.bubble.actionBtn.style.display = 'none';
+            const advanceFn = () => {
+                this._isAutoAdvancing = true;
+                setTimeout(() => { if (this.bubble.actionBtn) this.bubble.actionBtn.click(); }, STEP_TRANSITION_MS);
+            };
+            if (step.cursor) {
+                this.cursor.launch(step, this.overlay.el, advanceFn);
+            } else {
+                advanceFn();
+            }
+        }
+    }
+
+    async _positionForStep(step, highlightBottom = false) {
+        await this.bubble.positionForStep(step, {
+            overlay: this.overlay.el,
+            container: this.avatar.container,
+            img: this.avatar.img,
+            imgWrapper: this.avatar.imgWrapper,
+            videoEl: this.avatar.videoEl,
+            isMobile: this.isMobile(),
+            config: this.config.options,
+        }, highlightBottom);
+    }
+
+    _advance() {
+        this._lastDirection = 1;
+        this.autoNext.clear();
+        if (this.bubble.pauseBtn) this.bubble.pauseBtn.style.display = 'none';
+        this._cleanupAnimations();
+        const step = this.steps[this.currentStep];
+
+        if (step && step.redirect) {
+            window.location.href = step.redirect;
+            return;
+        }
+
+        if (this.currentStep < this.steps.length - 1) {
+            this.bubble.hide();
+            setTimeout(() => { this._showStep(this.currentStep + 1); }, STEP_TRANSITION_MS);
+        } else {
+            this._close();
+        }
+    }
+
+    _close() {
+        this._running = false;
+        this._readyContext = null;
+        this.autoNext.clear();
+        this._cleanupAnimations();
+
+        if (this._orientationHandler) {
+            window.removeEventListener('orientationchange', this._orientationHandler);
+            this._orientationHandler = null;
+        }
+        if (this._resizeHandler) {
+            window.removeEventListener('resize', this._resizeHandler);
+            this._resizeHandler = null;
+        }
+
+        this.typewriter.destroy();
+        this.bubble.destroy();
+        this.overlay.destroy();
+        this.avatar.destroy();
+    }
+
+    _cleanupAnimations() {
+        // If highlight was active, overlay was transparent — restore dimmed during transition
+        if (this._hasActiveHighlight) {
+            this._hasActiveHighlight = false;
+            this.overlay.setMode('dimmed');
+        }
+        this.cursor.destroy();
+        this.highlight.destroy();
+        this.hoverForcer.clearAll();
+        this.options.destroy();
+    }
+}

package/tutorials/index.js

@@ -0,0 +1,2 @@
+export { TutorialEngine } from './TutorialEngine.js';
+export { TutorialConfig } from './TutorialConfig.js';

package/tutorials/modules/AutoNext.js

@@ -0,0 +1,86 @@
+import { gsap } from 'gsap';
+
+/**
+ * Auto-advance timer with a visual progress bar.
+ */
+export class AutoNext {
+    constructor() {
+        this.timer = null;
+        this.tween = null;
+        this.bar = null;
+        this.paused = false;
+        this.remainingMs = 0;
+        this.startedAt = 0;
+    }
+
+    /**
+     * Start the auto-advance timer and progress bar.
+     * @param {number} seconds
+     * @param {HTMLElement} bubble - The bubble element (bar is appended here)
+     * @param {Function} onComplete
+     */
+    start(seconds, bubble, onComplete) {
+        this.clear();
+
+        const delayMs = seconds * 1000;
+        this.paused = false;
+        this.remainingMs = delayMs;
+        this.startedAt = Date.now();
+
+        this.bar = document.createElement('div');
+        this.bar.className = 'tutorial-auto-next-bar';
+        bubble.appendChild(this.bar);
+
+        this.tween = gsap.to(this.bar, {
+            width: '100%',
+            duration: seconds,
+            ease: 'none',
+        });
+
+        this.timer = setTimeout(() => {
+            onComplete();
+        }, delayMs);
+    }
+
+    pause() {
+        if (!this.timer || this.paused) return;
+        this.paused = true;
+        this.remainingMs = Math.max(0, this.remainingMs - (Date.now() - this.startedAt));
+        clearTimeout(this.timer);
+        this.timer = -1;
+        if (this.tween) this.tween.pause();
+    }
+
+    /**
+     * @param {Function} onComplete
+     */
+    resume(onComplete) {
+        if (!this.paused) return;
+        this.paused = false;
+        this.startedAt = Date.now();
+        if (this.tween) this.tween.resume();
+        this.timer = setTimeout(() => {
+            onComplete();
+        }, this.remainingMs);
+    }
+
+    clear() {
+        if (this.timer && this.timer !== -1) {
+            clearTimeout(this.timer);
+        }
+        this.timer = null;
+
+        if (this.tween) {
+            this.tween.kill();
+            this.tween = null;
+        }
+
+        if (this.bar) {
+            this.bar.remove();
+            this.bar = null;
+        }
+
+        this.paused = false;
+        this.remainingMs = 0;
+    }
+}

package/tutorials/modules/Avatar.js

@@ -0,0 +1,94 @@
+import { Z } from './Overlay.js';
+
+/**
+ * Avatar module: creates and manages the tutorial avatar DOM elements.
+ * When no avatar image is configured, renders a bubble-only layout (no avatar).
+ */
+export class Avatar {
+    constructor(engine) {
+        this.engine = engine;
+        this.container = null;
+        this.imgWrapper = null;
+        this.img = null;
+        this.videoEl = null;
+        this.hasAvatar = false;
+    }
+
+    /**
+     * Preload the avatar image. Returns null if no src provided.
+     */
+    preloadImage(src) {
+        if (!src) return Promise.resolve(null);
+
+        return new Promise((resolve) => {
+            const preload = new Image();
+            preload.src = src;
+            preload.onload = () => resolve(preload.src);
+            preload.onerror = () => {
+                console.warn('Avatar: image failed to load, skipping avatar', src);
+                resolve(null);
+            };
+        });
+    }
+
+    /**
+     * Build the avatar DOM structure.
+     * If no avatar image, creates container only (bubble-only mode).
+     */
+    create(config, avatarSrc) {
+        if (this.container) this.destroy();
+
+        this.hasAvatar = !!avatarSrc;
+
+        this.container = document.createElement('div');
+        this.container.id = 'tutorial-container';
+        this.container.className = 'tutorial-container';
+
+        if (!this.hasAvatar) {
+            this.container.classList.add('tutorial-container--no-avatar');
+            return;
+        }
+
+        this.imgWrapper = document.createElement('div');
+        this.imgWrapper.className = 'tutorial-img-wrapper';
+
+        this.img = document.createElement('img');
+        this.img.src = avatarSrc;
+        this.img.alt = 'Tutorial avatar';
+        this.img.className = 'tutorial-avatar';
+        this.img.style.height = config.avatarHeight;
+        this.img.style.maxHeight = config.avatarMaxHeight;
+
+        this.videoEl = null;
+        if (config.avatarVideo) {
+            this.img.style.display = 'none';
+            this.videoEl = document.createElement('video');
+            this.videoEl.src = config.avatarVideo;
+            this.videoEl.autoplay = true;
+            this.videoEl.muted = true;
+            this.videoEl.playsInline = true;
+            this.videoEl.className = 'tutorial-avatar-video';
+            this.videoEl.style.height = config.avatarHeight;
+            this.videoEl.style.maxHeight = config.avatarMaxHeight;
+            this.videoEl.addEventListener('ended', () => {
+                this.videoEl.style.display = 'none';
+                this.img.style.display = 'block';
+            });
+        }
+
+        if (this.videoEl) this.imgWrapper.appendChild(this.videoEl);
+        this.imgWrapper.appendChild(this.img);
+        this.container.appendChild(this.imgWrapper);
+    }
+
+    destroy() {
+        if (this.container) {
+            this.container.remove();
+            this.container = null;
+        }
+        this.imgWrapper = null;
+        this.img = null;
+        this.videoEl = null;
+        this.hasAvatar = false;
+    }
+}