js-kompo-utils 1.0.0

package/tutorials/step-builder/utils/bezier-editor.js

@@ -0,0 +1,379 @@
+import { createSvgEl } from '../../utils/svg.js';
+import { resolveElementCenter } from '../../utils/selectors.js';
+
+/**
+ * Interactive Bezier curve editor for cursor animation paths.
+ *
+ * Renders an SVG overlay showing the Bezier curve between two points
+ * (from / to), with draggable control-point handles.  The path is stored
+ * in normalized coordinates (0-1 range relative to the from-to bounding
+ * box) and written back to `step.cursor.svgPath` on every drag.
+ *
+ * Usage:
+ *   const editor = new BezierEditor(step, onChange);
+ *   editor.mount();          // show overlay + handles
+ *   editor.unmount();        // tear down
+ *   editor.refresh();        // recalculate positions (e.g. after resize)
+ */
+export class BezierEditor {
+    /**
+     * @param {Object} step - The step object whose cursor.svgPath is edited
+     * @param {Function} [onChange] - Called after every edit with the updated svgPath string
+     */
+    constructor(step, onChange) {
+        this.step = step;
+        this.onChange = onChange || (() => {});
+
+        /** @type {SVGSVGElement|null} */
+        this.svgEl = null;
+
+        /** Resolved pixel positions for from / to */
+        this._from = null;
+        this._to = null;
+
+        /** Normalized control points (0-1 relative to from-to delta) */
+        this._cp1 = { x: 0.3, y: 0.1 };
+        this._cp2 = { x: 0.7, y: 0.9 };
+
+        /** DOM references for drag handles */
+        this._handles = [];
+        /** Stored event listeners for cleanup */
+        this._listeners = [];
+        /** Endpoint dot elements */
+        this._dots = [];
+    }
+
+    // =============================================
+    // PUBLIC
+    // =============================================
+
+    /**
+     * Mount the editor: create SVG overlay and drag handles.
+     * No-op if the step has no cursor.from / cursor.to.
+     */
+    mount() {
+        this.unmount();
+
+        const c = this.step?.cursor;
+        if (!c?.from || !c?.to) return;
+
+        // Resolve endpoint pixel positions
+        this._from = resolveElementCenter(c.from, c.fromAnchor, this.step);
+        this._to = resolveElementCenter(c.to, c.toAnchor, this.step);
+        if (!this._from || !this._to) return;
+
+        // Parse existing svgPath into control points (or use defaults)
+        this._parsePath(c.svgPath);
+
+        // Create SVG overlay
+        this.svgEl = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+        Object.assign(this.svgEl.style, {
+            position: 'fixed',
+            inset: '0',
+            zIndex: '99998',
+            pointerEvents: 'none',
+        });
+        this.svgEl.setAttribute('width', '100%');
+        this.svgEl.setAttribute('height', '100%');
+        document.body.appendChild(this.svgEl);
+
+        // Draw the curve, control-point lines, handles, and endpoint dots
+        this._buildVisuals();
+    }
+
+    /**
+     * Remove all overlay elements and event listeners.
+     */
+    unmount() {
+        // Remove SVG overlay
+        if (this.svgEl?.parentNode) {
+            this.svgEl.parentNode.removeChild(this.svgEl);
+        }
+        this.svgEl = null;
+
+        // Remove drag handles and endpoint dots
+        for (const h of this._handles) {
+            if (h.parentNode) h.parentNode.removeChild(h);
+        }
+        for (const d of this._dots) {
+            if (d.parentNode) d.parentNode.removeChild(d);
+        }
+        this._handles = [];
+        this._dots = [];
+
+        // Detach document-level listeners
+        for (const { type, fn } of this._listeners) {
+            document.removeEventListener(type, fn);
+        }
+        this._listeners = [];
+    }
+
+    /**
+     * Recalculate endpoint positions and redraw (e.g. after scroll/resize).
+     */
+    refresh() {
+        if (!this.svgEl) return;
+
+        const c = this.step?.cursor;
+        if (!c?.from || !c?.to) return;
+
+        const newFrom = resolveElementCenter(c.from, c.fromAnchor, this.step);
+        const newTo = resolveElementCenter(c.to, c.toAnchor, this.step);
+        if (newFrom) this._from = newFrom;
+        if (newTo) this._to = newTo;
+
+        this._updateVisuals();
+    }
+
+    // =============================================
+    // INTERNAL -- SVG path parsing
+    // =============================================
+
+    /**
+     * Parse a normalized SVG path string ("M 0,0 C cx1,cy1 cx2,cy2 1,1")
+     * into _cp1 / _cp2.  Falls back to defaults if parsing fails.
+     */
+    _parsePath(svgPath) {
+        this._cp1 = { x: 0.3, y: 0.1 };
+        this._cp2 = { x: 0.7, y: 0.9 };
+
+        if (!svgPath) return;
+        const m = svgPath.match(/C\s*([-\d.]+),([-\d.]+)\s+([-\d.]+),([-\d.]+)/);
+        if (m) {
+            this._cp1 = { x: parseFloat(m[1]), y: parseFloat(m[2]) };
+            this._cp2 = { x: parseFloat(m[3]), y: parseFloat(m[4]) };
+        }
+    }
+
+    /**
+     * Serialize _cp1 / _cp2 back into a normalized SVG path string and
+     * write it to the step.
+     */
+    _syncPath() {
+        const path =
+            'M 0,0 C ' +
+            this._cp1.x.toFixed(2) + ',' + this._cp1.y.toFixed(2) + ' ' +
+            this._cp2.x.toFixed(2) + ',' + this._cp2.y.toFixed(2) + ' 1,1';
+
+        if (this.step?.cursor) {
+            this.step.cursor.svgPath = path;
+        }
+        this.onChange(path);
+    }
+
+    // =============================================
+    // INTERNAL -- Visual construction & update
+    // =============================================
+
+    /**
+     * Create all SVG + DOM elements for the overlay.
+     */
+    _buildVisuals() {
+        // Bezier curve path (dashed gold line)
+        this._curvePath = createSvgEl('path', {
+            fill: 'none',
+            stroke: '#ffd700',
+            'stroke-width': '2.5',
+            'stroke-dasharray': '8,4',
+        });
+        this.svgEl.appendChild(this._curvePath);
+
+        // Control-point guidelines (dashed cyan lines)
+        this._cpLine1 = createSvgEl('line', {
+            stroke: '#4fc3f7',
+            'stroke-width': '1',
+            'stroke-dasharray': '4,3',
+        });
+        this._cpLine2 = createSvgEl('line', {
+            stroke: '#4fc3f7',
+            'stroke-width': '1',
+            'stroke-dasharray': '4,3',
+        });
+        this.svgEl.appendChild(this._cpLine1);
+        this.svgEl.appendChild(this._cpLine2);
+
+        // Endpoint dots (from = green, to = red) -- plain divs for z-index
+        this._dots.push(this._createDot(this._from, '#4caf50'));
+        this._dots.push(this._createDot(this._to, '#f44336'));
+
+        // Draggable control-point handles
+        const h1 = this._createHandle('#ff9800');
+        const h2 = this._createHandle('#e91e63');
+        this._handles.push(h1, h2);
+
+        this._makeDraggable(h1, (cx, cy) => {
+            const dx = this._to.x - this._from.x;
+            const dy = this._to.y - this._from.y;
+            if (dx === 0 && dy === 0) return;
+            this._cp1.x = (cx - this._from.x) / dx;
+            this._cp1.y = (cy - this._from.y) / dy;
+            this._updateVisuals();
+            this._syncPath();
+        });
+
+        this._makeDraggable(h2, (cx, cy) => {
+            const dx = this._to.x - this._from.x;
+            const dy = this._to.y - this._from.y;
+            if (dx === 0 && dy === 0) return;
+            this._cp2.x = (cx - this._from.x) / dx;
+            this._cp2.y = (cy - this._from.y) / dy;
+            this._updateVisuals();
+            this._syncPath();
+        });
+
+        this._updateVisuals();
+    }
+
+    /**
+     * Update all visual positions from current state (_from, _to, _cp1, _cp2).
+     */
+    _updateVisuals() {
+        const f = this._from;
+        const t = this._to;
+        const dx = t.x - f.x;
+        const dy = t.y - f.y;
+
+        // Absolute pixel positions of control points
+        const c1x = f.x + this._cp1.x * dx;
+        const c1y = f.y + this._cp1.y * dy;
+        const c2x = f.x + this._cp2.x * dx;
+        const c2y = f.y + this._cp2.y * dy;
+
+        // Bezier curve
+        this._curvePath.setAttribute(
+            'd',
+            `M ${f.x},${f.y} C ${c1x},${c1y} ${c2x},${c2y} ${t.x},${t.y}`
+        );
+
+        // Guideline from start -> cp1
+        this._cpLine1.setAttribute('x1', f.x);
+        this._cpLine1.setAttribute('y1', f.y);
+        this._cpLine1.setAttribute('x2', c1x);
+        this._cpLine1.setAttribute('y2', c1y);
+
+        // Guideline from end -> cp2
+        this._cpLine2.setAttribute('x1', t.x);
+        this._cpLine2.setAttribute('y1', t.y);
+        this._cpLine2.setAttribute('x2', c2x);
+        this._cpLine2.setAttribute('y2', c2y);
+
+        // Handle positions
+        if (this._handles[0]) {
+            this._handles[0].style.left = c1x + 'px';
+            this._handles[0].style.top = c1y + 'px';
+        }
+        if (this._handles[1]) {
+            this._handles[1].style.left = c2x + 'px';
+            this._handles[1].style.top = c2y + 'px';
+        }
+
+        // Endpoint dots
+        if (this._dots[0]) {
+            this._dots[0].style.left = f.x + 'px';
+            this._dots[0].style.top = f.y + 'px';
+        }
+        if (this._dots[1]) {
+            this._dots[1].style.left = t.x + 'px';
+            this._dots[1].style.top = t.y + 'px';
+        }
+    }
+
+    // =============================================
+    // INTERNAL -- DOM element factories
+    // =============================================
+
+    /**
+     * Create a colored endpoint dot (non-draggable).
+     * @param {{x: number, y: number}} pos
+     * @param {string} color
+     * @returns {HTMLDivElement}
+     */
+    _createDot(pos, color) {
+        const dot = document.createElement('div');
+        Object.assign(dot.style, {
+            position: 'fixed',
+            width: '14px',
+            height: '14px',
+            borderRadius: '50%',
+            backgroundColor: color,
+            border: '2px solid #fff',
+            pointerEvents: 'none',
+            zIndex: '99999',
+            transform: 'translate(-50%, -50%)',
+            left: pos.x + 'px',
+            top: pos.y + 'px',
+        });
+        document.body.appendChild(dot);
+        return dot;
+    }
+
+    /**
+     * Create a draggable control-point handle.
+     * @param {string} color
+     * @returns {HTMLDivElement}
+     */
+    _createHandle(color) {
+        const h = document.createElement('div');
+        Object.assign(h.style, {
+            position: 'fixed',
+            width: '12px',
+            height: '12px',
+            borderRadius: '50%',
+            backgroundColor: color,
+            border: '2px solid #fff',
+            cursor: 'grab',
+            zIndex: '99999',
+            transform: 'translate(-50%, -50%)',
+        });
+        document.body.appendChild(h);
+        return h;
+    }
+
+    /**
+     * Make a handle element draggable (mouse + touch).
+     * Calls `onDrag(clientX, clientY)` on every move.
+     *
+     * @param {HTMLDivElement} handle
+     * @param {Function} onDrag - (clientX, clientY) => void
+     */
+    _makeDraggable(handle, onDrag) {
+        let dragging = false;
+
+        const startDrag = (e) => {
+            e.preventDefault();
+            e.stopPropagation();
+            dragging = true;
+            handle.style.cursor = 'grabbing';
+        };
+
+        const onMoveXY = (clientX, clientY) => {
+            if (!dragging) return;
+            onDrag(clientX, clientY);
+        };
+
+        const onMouseMove = (e) => onMoveXY(e.clientX, e.clientY);
+        const onTouchMove = (e) => onMoveXY(e.touches[0].clientX, e.touches[0].clientY);
+
+        const stopDrag = () => {
+            if (dragging) {
+                dragging = false;
+                handle.style.cursor = 'grab';
+            }
+        };
+
+        handle.addEventListener('mousedown', startDrag);
+        handle.addEventListener('touchstart', startDrag);
+
+        document.addEventListener('mousemove', onMouseMove);
+        document.addEventListener('mouseup', stopDrag);
+        document.addEventListener('touchmove', onTouchMove);
+        document.addEventListener('touchend', stopDrag);
+
+        this._listeners.push(
+            { type: 'mousemove', fn: onMouseMove },
+            { type: 'mouseup', fn: stopDrag },
+            { type: 'touchmove', fn: onTouchMove },
+            { type: 'touchend', fn: stopDrag },
+        );
+    }
+}

package/tutorials/step-builder/utils/code-generator.js

@@ -0,0 +1,127 @@
+/**
+ * Code generation utilities for the step builder.
+ * Produces clean JSON output from step data, omitting default/empty values
+ * to keep the output minimal and readable.
+ */
+
+/**
+ * Generate a clean plain object for a single step.
+ * Removes default/empty values so only meaningful fields remain.
+ *
+ * @param {Object} step - A step configuration object
+ * @returns {Object} Cleaned step object (not stringified)
+ */
+export function generateStepJson(step) {
+    const out = {};
+
+    // Short-circuit for silentClick-only steps
+    if (step.silentClick) {
+        out.silentClick = step.silentClick;
+        return out;
+    }
+
+    if (step.html) out.html = step.html;
+    if (step.overlay === false) out.overlay = false;
+    if (typeof step.showBack === 'number') out.showBack = step.showBack;
+    else if (step.showBack) out.showBack = true;
+    if (step.position && step.position !== 'left') out.position = step.position;
+    if (step.align && step.align !== 'center') out.align = step.align;
+    if (step.chatMode) out.chatMode = true;
+    if (step.chatMaxWidth) out.chatMaxWidth = step.chatMaxWidth;
+    if (step.clearOverlay) out.clearOverlay = true;
+    if (step.positionTarget) out.positionTarget = step.positionTarget;
+    if (step.showIf) out.showIf = step.showIf;
+
+    // Cursor
+    if (step.cursor && step.cursor.from) {
+        const c = step.cursor;
+        const cursor = { from: c.from };
+        if (c.fromAnchor) cursor.fromAnchor = c.fromAnchor;
+        if (c.to) {
+            cursor.to = c.to;
+            if (c.toAnchor) cursor.toAnchor = c.toAnchor;
+        }
+        if (c.svgPath && !c.waypoints) cursor.svgPath = c.svgPath;
+        if (c.duration && c.duration !== 1.5) cursor.duration = c.duration;
+        if (c.delay && c.delay > 0) cursor.delay = c.delay;
+        if (c.ease && c.ease !== 'power2.out') cursor.ease = c.ease;
+        if (c.click) cursor.click = true;
+        if (c.loop) cursor.loop = true;
+        if (c.waypoints && c.waypoints.length) {
+            cursor.waypoints = c.waypoints.map((wp) => {
+                const entry = { target: wp.target };
+                if (wp.svgPath) entry.svgPath = wp.svgPath;
+                if (wp.action && wp.action !== 'path') entry.action = wp.action;
+                if (wp.pause && wp.pause > 0) entry.pause = wp.pause;
+                return entry;
+            });
+        }
+        out.cursor = cursor;
+    }
+
+    // Highlight
+    if (step.highlight?.groups?.length) {
+        const hl = { groups: [] };
+        for (const g of step.highlight.groups) {
+            const elems = g.elements || g;
+            if (Array.isArray(elems)) hl.groups.push(elems);
+        }
+        if (step.highlight.padding !== undefined) hl.padding = step.highlight.padding;
+        if (step.highlight.borderRadius !== undefined) hl.borderRadius = step.highlight.borderRadius;
+        if (step.highlight.blockOutside) hl.blockOutside = true;
+        out.highlight = hl;
+    }
+
+    // Hover
+    if (step.hover) out.hover = step.hover;
+
+    // Scroll
+    if (step.scrollTo) out.scrollTo = step.scrollTo;
+    if (step.scrollInside?.selector) {
+        const si = { selector: step.scrollInside.selector };
+        if (step.scrollInside.to !== undefined) si.to = step.scrollInside.to;
+        if (step.scrollInside.by !== undefined) si.by = step.scrollInside.by;
+        if (step.scrollInside.duration) si.duration = step.scrollInside.duration;
+        out.scrollInside = si;
+    }
+
+    // Options
+    if (step.options?.length) out.options = step.options;
+
+    // Advance
+    if (step.autoNext) out.autoNext = step.autoNext;
+    if (step.afterAnimation) out.afterAnimation = true;
+
+    // Redirect
+    if (step.redirect) out.redirect = step.redirect;
+
+    return out;
+}
+
+/**
+ * Generate the full tutorial JSON string with options and all steps.
+ *
+ * @param {Object[]} steps - Array of step configuration objects
+ * @param {Object} [config] - Engine config object (optional)
+ * @returns {string} Pretty-printed JSON string
+ */
+export function generateFullJson(steps, config) {
+    const cleanSteps = steps.map(generateStepJson);
+    const output = { steps: cleanSteps };
+
+    // Include non-default config options
+    if (config?.options) {
+        const opts = {};
+        const defaults = config.constructor?.DEFAULTS || {};
+        for (const [key, value] of Object.entries(config.options)) {
+            if (value !== defaults[key]) {
+                opts[key] = value;
+            }
+        }
+        if (Object.keys(opts).length > 0) {
+            output.options = opts;
+        }
+    }
+
+    return JSON.stringify(output, null, 2);
+}

package/tutorials/step-builder/utils/element-picker.js

@@ -0,0 +1,125 @@
+import { bestSelector } from '../../utils/selectors.js';
+
+/**
+ * Interactive element picker. Returns a Promise that resolves with the
+ * CSS selector of the clicked element, or null if cancelled (Escape key).
+ */
+export function pickElement() {
+    return new Promise((resolve) => {
+        const hoverOutline = document.createElement('div');
+        hoverOutline.className = 'tutorial-picker-highlight';
+
+        const hoverLabel = document.createElement('div');
+        hoverLabel.className = 'tutorial-picker-label';
+
+        document.body.appendChild(hoverOutline);
+        document.body.appendChild(hoverLabel);
+        document.body.style.cursor = 'crosshair';
+
+        const builderPanel = document.getElementById('tutorial-step-builder');
+
+        function getElementUnder(x, y) {
+            hoverOutline.style.display = 'none';
+            hoverLabel.style.display = 'none';
+
+            // Temporarily hide tutorial elements so we can pick beneath them
+            const tutorialOverlay = document.getElementById('tutorial-overlay');
+            const tutorialContainer = document.getElementById('tutorial-container');
+            const tutorialHighlight = document.querySelector('.tutorial-highlight-svg');
+
+            if (tutorialOverlay) tutorialOverlay.style.display = 'none';
+            if (tutorialContainer) tutorialContainer.style.display = 'none';
+            if (tutorialHighlight) tutorialHighlight.style.display = 'none';
+
+            const found = document.elementFromPoint(x, y);
+
+            if (tutorialOverlay) tutorialOverlay.style.display = '';
+            if (tutorialContainer) tutorialContainer.style.display = '';
+            if (tutorialHighlight) tutorialHighlight.style.display = '';
+
+            hoverOutline.style.display = '';
+            hoverLabel.style.display = '';
+            return found;
+        }
+
+        function isBuilderElement(el) {
+            return builderPanel && builderPanel.contains(el);
+        }
+
+        function onMove(e) {
+            const target = getElementUnder(e.clientX, e.clientY);
+            if (
+                target &&
+                target !== hoverOutline &&
+                target !== hoverLabel &&
+                !isBuilderElement(target)
+            ) {
+                const rect = target.getBoundingClientRect();
+                Object.assign(hoverOutline.style, {
+                    display: 'block',
+                    left: rect.left + 'px',
+                    top: rect.top + 'px',
+                    width: rect.width + 'px',
+                    height: rect.height + 'px',
+                });
+
+                const sel = bestSelector(target);
+                hoverLabel.textContent = sel;
+                hoverLabel.style.display = 'block';
+                hoverLabel.style.left = rect.left + 'px';
+                hoverLabel.style.top = (rect.top - 22) + 'px';
+            } else {
+                hoverOutline.style.display = 'none';
+                hoverLabel.style.display = 'none';
+            }
+        }
+
+        function cleanup() {
+            document.removeEventListener('mousemove', onMove, true);
+            document.removeEventListener('click', onClick, true);
+            document.removeEventListener('touchend', onTouch, true);
+            document.removeEventListener('keydown', onEsc, true);
+
+            if (hoverOutline.parentNode) hoverOutline.parentNode.removeChild(hoverOutline);
+            if (hoverLabel.parentNode) hoverLabel.parentNode.removeChild(hoverLabel);
+            document.body.style.cursor = '';
+        }
+
+        function onClick(e) {
+            e.preventDefault();
+            e.stopPropagation();
+
+            const target = getElementUnder(e.clientX, e.clientY);
+            cleanup();
+
+            if (target && !isBuilderElement(target)) {
+                const selector = bestSelector(target);
+                resolve(selector);
+            } else {
+                resolve(null);
+            }
+        }
+
+        function onTouch(e) {
+            const touch = e.changedTouches[0];
+            onClick({
+                clientX: touch.clientX,
+                clientY: touch.clientY,
+                preventDefault() {},
+                stopPropagation() {},
+            });
+        }
+
+        function onEsc(e) {
+            if (e.key === 'Escape') {
+                cleanup();
+                resolve(null);
+            }
+        }
+
+        document.addEventListener('mousemove', onMove, true);
+        document.addEventListener('click', onClick, true);
+        document.addEventListener('touchend', onTouch, true);
+        document.addEventListener('keydown', onEsc, true);
+    });
+}