js-kompo-utils 1.0.0

package/tutorials/modules/Cursor.js

@@ -0,0 +1,315 @@
+import { gsap } from 'gsap';
+import { MotionPathPlugin } from 'gsap/MotionPathPlugin';
+import { resolveElementCenter, resolveRef } from '../utils/selectors.js';
+import { denormalizeSvgPath } from '../utils/svg.js';
+import { Z } from './Overlay.js';
+
+gsap.registerPlugin(MotionPathPlugin);
+
+const DEFAULT_CURSOR_SIZE = 'clamp(32px, 8vw, 48px)';
+const DEFAULT_SVG_PATH = 'M 0,0 C 0.3,0.1 0.7,0.9 1,1';
+
+/**
+ * Cursor module: animated cursor element using GSAP MotionPathPlugin.
+ */
+export class Cursor {
+    constructor(engine) {
+        this.engine = engine;
+        this.el = null;
+        this.timeline = null;
+    }
+
+    /**
+     * Create a cursor DOM element (desktop image or mobile dot).
+     * @param {Object} cfg - Cursor configuration
+     * @param {boolean} [isMobile=false]
+     * @returns {HTMLElement}
+     */
+    create(cfg = {}, isMobile = false) {
+        let cursorEl;
+
+        if (isMobile) {
+            cursorEl = document.createElement('div');
+            cursorEl.className = 'tutorial-cursor tutorial-cursor--mobile';
+        } else {
+            cursorEl = document.createElement('img');
+            cursorEl.src = cfg.image || '/images/tutorial-cursor.svg';
+            cursorEl.className = 'tutorial-cursor';
+            cursorEl.style.width = DEFAULT_CURSOR_SIZE;
+            cursorEl.style.height = DEFAULT_CURSOR_SIZE;
+        }
+
+        document.body.appendChild(cursorEl);
+        return cursorEl;
+    }
+
+    /**
+     * Launch a cursor animation, choosing waypoints or simple based on step config.
+     * @param {Object} step
+     * @param {HTMLElement} overlay
+     * @param {Function} [onComplete]
+     * @returns {{ el, timeline, destroy } | null}
+     */
+    launch(step, overlay, onComplete) {
+        if (!step.cursor) {
+            onComplete?.();
+            return null;
+        }
+        return step.cursor.waypoints
+            ? this.animateWaypoints(step, overlay, onComplete)
+            : this.animate(step, overlay, onComplete);
+    }
+
+    /**
+     * Single from->to cursor animation with optional click pulse at end.
+     * @param {Object} step
+     * @param {HTMLElement} overlay
+     * @param {Function} [onComplete]
+     * @returns {{ el, timeline, destroy } | null}
+     */
+    animate(step, overlay, onComplete) {
+        const cfg = step.cursor;
+        if (!cfg) {
+            onComplete?.();
+            return null;
+        }
+
+        const fromPos = resolveElementCenter(cfg.from, cfg.fromAnchor, step);
+        const toPos = resolveElementCenter(cfg.to, cfg.toAnchor, step);
+        if (!fromPos || !toPos) {
+            console.warn('Cursor.animate: could not resolve from/to selectors', cfg.from, cfg.to);
+            onComplete?.();
+            return null;
+        }
+
+        const isMobile = this.engine.isMobile?.() ?? false;
+        const cursorEl = this.create(cfg, isMobile);
+        this.el = cursorEl;
+
+        const svgPathNorm = cfg.svgPath || DEFAULT_SVG_PATH;
+        const realPath = denormalizeSvgPath(svgPathNorm, fromPos, toPos);
+        const devMode = this.engine?.config?.get('devMode');
+
+        const timeline = gsap.timeline({
+            onComplete: () => {
+                if (cfg.click) {
+                    const cursorRect = cursorEl.getBoundingClientRect();
+                    const pulseX = cursorRect.left + cursorRect.width * 0.15;
+                    const pulseY = cursorRect.top + cursorRect.height * 0.1;
+                    this.createClickPulse(pulseX, pulseY);
+
+                    gsap.to(cursorEl, {
+                        scale: 0.7,
+                        duration: 0.1,
+                        yoyo: true,
+                        repeat: 1,
+                        onComplete: () => {
+                            if (!devMode) {
+                                const targetEl = document.querySelector(resolveRef(cfg.to, step));
+                                if (targetEl && typeof targetEl.click === 'function') {
+                                    targetEl.click();
+                                }
+                            }
+                            if (cfg.loop) {
+                                gsap.set(cursorEl, { x: fromPos.x, y: fromPos.y, scale: 1 });
+                                timeline.restart();
+                            } else {
+                                onComplete?.();
+                            }
+                        },
+                    });
+                } else {
+                    if (cfg.loop) {
+                        gsap.set(cursorEl, { x: fromPos.x, y: fromPos.y });
+                        timeline.restart();
+                    } else {
+                        onComplete?.();
+                    }
+                }
+            },
+        });
+
+        this.timeline = timeline;
+
+        gsap.set(cursorEl, { x: fromPos.x, y: fromPos.y });
+        timeline.to(cursorEl, { opacity: 1, duration: 0.3 });
+        timeline.to(cursorEl, {
+            duration: cfg.duration || 1.5,
+            ease: cfg.ease || 'power2.inOut',
+            motionPath: { path: realPath },
+        });
+
+        if (cfg.delay) {
+            timeline.delay(cfg.delay);
+        }
+
+        return {
+            el: cursorEl,
+            timeline,
+            destroy: () => {
+                timeline.kill();
+                cursorEl.remove();
+            },
+        };
+    }
+
+    /**
+     * Multi-point cursor animation with click/hover actions at each waypoint.
+     * @param {Object} step
+     * @param {HTMLElement} overlay
+     * @param {Function} [onComplete]
+     * @returns {{ el, timeline, destroy } | null}
+     */
+    animateWaypoints(step, overlay, onComplete) {
+        const cfg = step.cursor;
+        if (!cfg || !cfg.waypoints || !cfg.waypoints.length) {
+            return this.animate(step, overlay, onComplete);
+        }
+
+        const isMobile = this.engine.isMobile?.() ?? false;
+        const cursorEl = this.create(cfg, isMobile);
+        this.el = cursorEl;
+
+        const fromPos = resolveElementCenter(cfg.from, null, step);
+        if (!fromPos) {
+            cursorEl.remove();
+            this.el = null;
+            onComplete?.();
+            return null;
+        }
+
+        const devMode = this.engine?.config?.get('devMode');
+
+        const timeline = gsap.timeline({
+            delay: cfg.delay || 0,
+            onComplete: () => {
+                if (cfg.loop) {
+                    gsap.set(cursorEl, { x: fromPos.x, y: fromPos.y });
+                    timeline.restart();
+                } else {
+                    onComplete?.();
+                }
+            },
+        });
+
+        this.timeline = timeline;
+
+        gsap.set(cursorEl, { x: fromPos.x, y: fromPos.y });
+        timeline.to(cursorEl, { opacity: 1, duration: 0.3 });
+
+        let currentFrom = fromPos;
+
+        cfg.waypoints.forEach((wp) => {
+            const wpPos = resolveElementCenter(wp.target, null, step);
+            if (!wpPos) return;
+
+            const wpPath = wp.svgPath || DEFAULT_SVG_PATH;
+            const realPath = denormalizeSvgPath(wpPath, currentFrom, wpPos);
+            const segDuration = (cfg.duration || 1.5) / cfg.waypoints.length;
+
+            timeline.to(cursorEl, {
+                duration: segDuration,
+                ease: cfg.ease || 'power2.inOut',
+                motionPath: { path: realPath },
+            });
+
+            const action = wp.action || 'path';
+
+            if (action === 'click') {
+                timeline.call(() => {
+                    const cr = cursorEl.getBoundingClientRect();
+                    this.createClickPulse(
+                        cr.left + cr.width * 0.15,
+                        cr.top + cr.height * 0.1
+                    );
+                });
+                timeline.to(cursorEl, {
+                    scale: 0.7,
+                    duration: 0.1,
+                    yoyo: true,
+                    repeat: 1,
+                });
+                ((target) => {
+                    timeline.call(() => {
+                        if (!devMode) {
+                            const el = document.querySelector(target);
+                            if (el) el.click();
+                        }
+                    });
+                })(wp.target);
+            } else if (action === 'hover') {
+                ((target) => {
+                    timeline.call(() => {
+                        const el = document.querySelector(target);
+                        if (el) {
+                            this.engine.forceHover?.(el);
+                            el.classList.add('tutorial-force-hover');
+                            el.dispatchEvent(new MouseEvent('mouseenter', { bubbles: true }));
+                            el.dispatchEvent(new MouseEvent('mouseover', { bubbles: true }));
+                        }
+                    });
+                    timeline.to(cursorEl, { duration: 0.5 });
+                })(wp.target);
+            }
+
+            if (wp.pause && wp.pause > 0) {
+                timeline.to(cursorEl, { duration: wp.pause });
+            }
+
+            currentFrom = wpPos;
+        });
+
+        return {
+            el: cursorEl,
+            timeline,
+            destroy: () => {
+                timeline.kill();
+                cursorEl.remove();
+            },
+        };
+    }
+
+    /**
+     * Create a click-pulse visual effect at the given coordinates.
+     * @param {number} x
+     * @param {number} y
+     */
+    createClickPulse(x, y) {
+        this._createRing(x, y, 0.25, 3, 0.7, 0);
+        this._createRing(x, y, 0.15, 2, 0.5, 0.15);
+    }
+
+    /**
+     * @private
+     */
+    _createRing(x, y, bgOpacity, scale, duration, delay) {
+        const ring = document.createElement('div');
+        ring.className = 'tutorial-pulse-ring';
+        ring.style.left = x + 'px';
+        ring.style.top = y + 'px';
+        ring.style.backgroundColor = `rgba(255, 68, 68, ${bgOpacity})`;
+        ring.style.setProperty('--pulse-scale', String(scale));
+        ring.style.setProperty('--pulse-duration', duration + 's');
+        ring.style.setProperty('--pulse-delay', delay + 's');
+
+        document.body.appendChild(ring);
+
+        ring.addEventListener('animationend', () => {
+            ring.remove();
+        });
+
+        setTimeout(() => {
+            if (ring.parentNode) ring.remove();
+        }, (duration + delay) * 1000 + 100);
+    }
+
+    /**
+     * Kill the GSAP timeline and remove the cursor element.
+     */
+    destroy() {
+        this.timeline?.kill();
+        this.el?.remove();
+        this.el = null;
+        this.timeline = null;
+    }
+}

package/tutorials/modules/Highlight.js

@@ -0,0 +1,282 @@
+/**
+ * SVG overlay with cutout windows around highlighted elements.
+ *
+ * Creates an SVG covering the viewport with a semi-transparent dark layer,
+ * using the even-odd fill rule to cut out rounded rectangular windows
+ * around specified element groups.
+ */
+
+import { createSvgEl } from '../utils/svg.js';
+import { waitForStableHighlight } from '../utils/stability.js';
+import { Z } from './Overlay.js';
+
+/**
+ * Build SVG path data for highlight cutouts from groups config.
+ * @param {Array} groups
+ * @param {number} padding
+ * @param {number} radius
+ * @returns {{ pathData: string, rects: Array }}
+ */
+function buildHighlightPathData(groups, padding, radius) {
+    const W = window.innerWidth;
+    const H = window.innerHeight;
+
+    let d = `M 0,0 L ${W},0 L ${W},${H} L 0,${H} Z `;
+    const cutoutRects = [];
+
+    for (const group of groups) {
+        const selectors = group.elements || group;
+        if (!selectors.length) continue;
+
+        let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+
+        for (const sel of selectors) {
+            const el = document.querySelector(sel);
+            if (!el) continue;
+            const rect = el.getBoundingClientRect();
+            if (rect.left < minX) minX = rect.left;
+            if (rect.top < minY) minY = rect.top;
+            if (rect.right > maxX) maxX = rect.right;
+            if (rect.bottom > maxY) maxY = rect.bottom;
+        }
+
+        if (minX === Infinity) continue;
+
+        const x = minX - padding;
+        const y = minY - padding;
+        const w = (maxX - minX) + padding * 2;
+        const h = (maxY - minY) + padding * 2;
+        const r = Math.min(radius, w / 2, h / 2);
+
+        cutoutRects.push({ x, y, w, h, r });
+
+        d += `M ${x + r},${y}`
+           + ` L ${x + w - r},${y}`
+           + ` A ${r},${r} 0 0 1 ${x + w},${y + r}`
+           + ` L ${x + w},${y + h - r}`
+           + ` A ${r},${r} 0 0 1 ${x + w - r},${y + h}`
+           + ` L ${x + r},${y + h}`
+           + ` A ${r},${r} 0 0 1 ${x},${y + h - r}`
+           + ` L ${x},${y + r}`
+           + ` A ${r},${r} 0 0 1 ${x + r},${y} Z `;
+    }
+
+    return { pathData: d, rects: cutoutRects };
+}
+
+/**
+ * Create an SVG <rect> border element for a highlight cutout.
+ * @param {{ x, y, w, h, r }} cr
+ * @returns {SVGRectElement}
+ */
+function createBorderRect(cr) {
+    return createSvgEl('rect', {
+        x: cr.x,
+        y: cr.y,
+        width: cr.w,
+        height: cr.h,
+        rx: cr.r,
+        fill: 'none',
+        stroke: '#ffd700',
+        'stroke-width': '2',
+    });
+}
+
+/**
+ * Debounced scroll/resize listener using requestAnimationFrame.
+ * @param {Function} callback
+ * @returns {Function} cleanup
+ */
+function onScrollResize(callback) {
+    let rafId = null;
+
+    function handler() {
+        if (!rafId) {
+            rafId = requestAnimationFrame(() => {
+                rafId = null;
+                callback();
+            });
+        }
+    }
+
+    window.addEventListener('scroll', handler, true);
+    window.addEventListener('resize', handler);
+
+    return function cleanup() {
+        window.removeEventListener('scroll', handler, true);
+        window.removeEventListener('resize', handler);
+        if (rafId) {
+            cancelAnimationFrame(rafId);
+            rafId = null;
+        }
+    };
+}
+
+export class Highlight {
+    constructor(engine) {
+        this.engine = engine;
+        this.svgEl = null;
+        this.pathEl = null;
+        this.cleanupFn = null;
+        this._config = null;
+        this._generation = 0;
+        this._cancelStability = null;
+    }
+
+    /**
+     * Auto-scroll to the first highlighted element if off-screen.
+     * @param {object} step
+     * @param {boolean} isMobile
+     * @returns {{ highlightBottom: boolean }}
+     */
+    scrollToElements(step, isMobile) {
+        let highlightBottom = false;
+        const hlConfig = step.highlight;
+        if (!hlConfig) return { highlightBottom };
+
+        let firstSel = null;
+        if (hlConfig.selector) {
+            firstSel = hlConfig.selector;
+        } else if (hlConfig.groups && hlConfig.groups.length) {
+            const g = hlConfig.groups[0];
+            const elems = g.elements || g;
+            if (elems.length) firstSel = elems[0];
+        }
+
+        if (firstSel) {
+            const hlFirstEl = document.querySelector(firstSel);
+            if (hlFirstEl) {
+                let hlRect = hlFirstEl.getBoundingClientRect();
+                if (hlRect.top < 0 || hlRect.bottom > window.innerHeight) {
+                    document.body.style.overflow = '';
+                    hlFirstEl.scrollIntoView({ behavior: 'smooth', block: 'center' });
+                    document.body.style.overflow = 'hidden';
+                }
+                hlRect = hlFirstEl.getBoundingClientRect();
+                if (isMobile) {
+                    highlightBottom = (hlRect.top + hlRect.height / 2) > window.innerHeight / 2;
+                }
+            }
+        }
+
+        return { highlightBottom };
+    }
+
+    /**
+     * Create the highlight overlay with cutout windows.
+     * @param {Object} config
+     * @returns {Highlight} this
+     */
+    create(config) {
+        if (!config) return this;
+
+        this.destroy();
+
+        if (config.selector && !config.groups) {
+            config = {
+                groups: [{ elements: [config.selector] }],
+                padding: config.padding || 8,
+                borderRadius: config.borderRadius || 8,
+            };
+        }
+
+        if (!config.groups || !config.groups.length) return this;
+
+        this._config = config;
+        this._generation++;
+        const gen = this._generation;
+        const padding = config.padding || 8;
+        const radius = config.borderRadius || 8;
+        const blockOutside = config.blockOutside || false;
+
+        this._cancelStability = waitForStableHighlight(config, () => {
+            if (gen !== this._generation) return;
+            this._build(padding, radius, blockOutside);
+        });
+
+        return this;
+    }
+
+    /** @private */
+    _build(padding, radius, blockOutside) {
+        const config = this._config;
+        if (!config) return;
+
+        const W = window.innerWidth;
+        const H = window.innerHeight;
+        this.svgEl = createSvgEl('svg', {
+            width: W,
+            height: H,
+            viewBox: `0 0 ${W} ${H}`,
+        });
+        this.svgEl.classList.add('tutorial-highlight-svg');
+        Object.assign(this.svgEl.style, {
+            position: 'fixed',
+            top: '0',
+            left: '0',
+            width: '100vw',
+            height: '100vh',
+            zIndex: String(Z.HIGHLIGHT),
+            pointerEvents: 'none',
+        });
+
+        const result = buildHighlightPathData(config.groups, padding, radius);
+
+        this.pathEl = createSvgEl('path', {
+            d: result.pathData,
+            fill: 'rgba(0,0,0,0.55)',
+            'fill-rule': 'evenodd',
+            'pointer-events': blockOutside ? 'fill' : 'none',
+        });
+        this.svgEl.appendChild(this.pathEl);
+
+        for (const cr of result.rects) {
+            this.svgEl.appendChild(createBorderRect(cr));
+        }
+
+        document.body.appendChild(this.svgEl);
+
+        // Highlight SVG is now in DOM — overlay can safely go transparent
+        this.engine.overlay.setMode('transparent');
+
+        const cleanupScrollResize = onScrollResize(() => {
+            this._refresh(padding, radius);
+        });
+
+        this.cleanupFn = cleanupScrollResize;
+    }
+
+    /** @private */
+    _refresh(padding, radius) {
+        if (!this.svgEl || !this.pathEl || !this._config) return;
+
+        const W = window.innerWidth;
+        const H = window.innerHeight;
+        this.svgEl.setAttribute('width', W);
+        this.svgEl.setAttribute('height', H);
+        this.svgEl.setAttribute('viewBox', `0 0 ${W} ${H}`);
+
+        const result = buildHighlightPathData(this._config.groups, padding, radius);
+        this.pathEl.setAttribute('d', result.pathData);
+
+        const oldBorders = this.svgEl.querySelectorAll('rect');
+        for (const border of oldBorders) {
+            border.remove();
+        }
+        for (const cr of result.rects) {
+            this.svgEl.appendChild(createBorderRect(cr));
+        }
+    }
+
+    destroy() {
+        this._generation++;
+        this._cancelStability?.();
+        this._cancelStability = null;
+        this.cleanupFn?.();
+        this.svgEl?.remove();
+        this.svgEl = null;
+        this.pathEl = null;
+        this.cleanupFn = null;
+        this._config = null;
+    }
+}