js-kompo-utils 1.0.0

package/tutorials/modules/Typewriter.js

@@ -0,0 +1,132 @@
+/**
+ * Typewriter module: renders HTML content character-by-character.
+ *
+ * Walks DOM nodes, creates elements with their attributes, and types text
+ * nodes character-by-character. Supports click-to-skip.
+ */
+export class Typewriter {
+    constructor(engine) {
+        this.engine = engine;
+        this._skipped = false;
+        this._skipHandler = null;
+        this._callbackFired = false;
+    }
+
+    /**
+     * Typewrite HTML content into a container, node by node.
+     * @param {HTMLElement} container
+     * @param {string} html
+     * @param {number} speed - Milliseconds per character
+     * @param {Function} [onComplete]
+     */
+    type(container, html, speed, onComplete) {
+        this.destroy();
+        this._skipped = false;
+        this._callbackFired = false;
+
+        const fireCallback = () => {
+            if (this._callbackFired) return;
+            this._callbackFired = true;
+            onComplete?.();
+        };
+
+        const skipAll = () => {
+            if (this._skipped) return;
+            this._skipped = true;
+            container.innerHTML = html;
+            fireCallback();
+        };
+
+        this._skipHandler = skipAll;
+        document.addEventListener('click', skipAll, { once: true, capture: true });
+        document.addEventListener('touchstart', skipAll, { once: true, capture: true });
+
+        this._typewriteHtml(container, html, speed, () => {
+            this._removeSkipListeners();
+            fireCallback();
+        }, null);
+    }
+
+    skip() {
+        if (this._skipHandler) {
+            this._skipHandler();
+        }
+    }
+
+    destroy() {
+        this._removeSkipListeners();
+        this._skipped = true;
+        this._callbackFired = true;
+        this._skipHandler = null;
+    }
+
+    /** @private */
+    _removeSkipListeners() {
+        if (this._skipHandler) {
+            document.removeEventListener('click', this._skipHandler, true);
+            document.removeEventListener('touchstart', this._skipHandler, true);
+        }
+    }
+
+    /** @private */
+    _typewriteHtml(container, html, speed, callback, parentIsSkipped) {
+        const isSkipped = () => {
+            return this._skipped || (parentIsSkipped && parentIsSkipped());
+        };
+
+        const temp = document.createElement('div');
+        temp.innerHTML = html;
+        const nodes = Array.from(temp.childNodes);
+        let nodeIndex = 0;
+
+        const processNode = () => {
+            if (isSkipped()) return;
+            if (nodeIndex >= nodes.length) {
+                callback();
+                return;
+            }
+
+            const node = nodes[nodeIndex];
+            nodeIndex++;
+
+            if (node.nodeType === Node.TEXT_NODE) {
+                this._typewriteText(container, node.textContent, speed, processNode, isSkipped);
+            } else if (node.nodeType === Node.ELEMENT_NODE) {
+                const el = document.createElement(node.tagName);
+                for (let i = 0; i < node.attributes.length; i++) {
+                    el.setAttribute(node.attributes[i].name, node.attributes[i].value);
+                }
+                container.appendChild(el);
+                if (node.childNodes.length > 0) {
+                    this._typewriteHtml(el, node.innerHTML, speed, processNode, isSkipped);
+                } else {
+                    processNode();
+                }
+            } else {
+                processNode();
+            }
+        };
+
+        processNode();
+    }
+
+    /** @private */
+    _typewriteText(container, text, speed, callback, isSkipped) {
+        let i = 0;
+        const textNode = document.createTextNode('');
+        container.appendChild(textNode);
+
+        const tick = () => {
+            if (isSkipped && isSkipped()) return;
+            if (i < text.length) {
+                textNode.textContent += text.charAt(i);
+                i++;
+                setTimeout(tick, speed);
+            } else {
+                callback();
+            }
+        };
+
+        tick();
+    }
+}

package/tutorials/step-builder/step-builder-bridge.js

@@ -0,0 +1,436 @@
+/**
+ * StepBuilderBridge - Connects the TutorialStepBuilder Kompo Form to the
+ * TutorialEngine using Kompo's $k context (field, watchAll, panel, on).
+ *
+ * Initialized by TutorialStepBuilder.php onLoad handler which passes
+ * the real $k context. StepBuilderBridge class is pre-registered on
+ * window by KompoJsBuilder at boot time.
+ */
+
+import { pickElement } from './utils/element-picker.js';
+import { generateFullJson } from './utils/code-generator.js';
+
+const WATCHED_FIELDS = [
+    'sb-html', 'sb-overlay', 'sb-show-back',
+    'sb-position', 'sb-align', 'sb-chat-mode', 'sb-position-target',
+    'sb-advance', 'sb-auto-next-delay',
+    'sb-silent-click', 'sb-redirect', 'sb-show-if',
+    'sb-cursor-from', 'sb-cursor-to', 'sb-cursor-duration',
+    'sb-cursor-click', 'sb-cursor-loop',
+    'sb-highlight-elements', 'sb-highlight-mode',
+    'sb-hover',
+    'sb-scroll-to', 'sb-scroll-inside-selector', 'sb-scroll-inside-amount',
+];
+
+export class StepBuilderBridge {
+    /**
+     * @param {object} ctx - Kompo $k context from onLoad (field, watchAll, panel, on, etc.)
+     * @param {TutorialEngine} engine
+     */
+    constructor(ctx, engine) {
+        this.ctx = ctx || {};
+        this.engine = engine || window.TutorialEngine;
+        this.steps = [{ html: '', overlay: true }];
+        this.selectedIndex = 0;
+
+        // Extract $k helpers with safe fallbacks
+        this._field = ctx?.field || (() => ({ value: '', set() {} }));
+        this._panel = ctx?.panel || (() => ({ fill() {} }));
+        this._watchAll = ctx?.watchAll || null;
+        this._on = ctx?.on || null;
+        this._el = ctx?.el || (() => null);
+
+        // Set data-sb for scoped styling
+        const panelEl = document.getElementById('tutorial-step-builder');
+        if (panelEl) panelEl.setAttribute('data-sb', '');
+
+        this._setupWatchers();
+        this._setupEventDelegation();
+
+        // Sync with engine when tutorial data loads
+        if (this.engine?.onReady) {
+            this.engine.onReady(() => this._initFromEngine());
+        }
+
+        // Fallback: catch tutorials started after bridge init
+        document.addEventListener('tutorial-step-change', () => {
+            if (!this.engine) this.engine = window.TutorialEngine;
+            if (this.engine?.steps?.length && this.steps.length <= 1 && !this.steps[0]?.html) {
+                this._initFromEngine();
+            }
+        });
+    }
+
+    // ─── Engine Sync ─────────────────────────────────────────────────
+
+    _initFromEngine() {
+        if (!this.engine?.steps?.length) return;
+        this.steps = this.engine.steps.map(s => ({ ...s }));
+        this.selectedIndex = Math.min(this.selectedIndex, this.steps.length - 1);
+        this._renderStepList();
+        this._syncStepToForm();
+        this._renderOptions();
+        this._updateOutput();
+    }
+
+    _previewCurrentStep() {
+        if (!this.engine) return;
+        this.engine.steps = this.steps;
+        this.engine.previewStep(this.selectedIndex);
+    }
+
+    // ─── Watchers (Kompo $k) ─────────────────────────────────────────
+
+    _setupWatchers() {
+        if (!this._watchAll) return;
+
+        this._watchAll(WATCHED_FIELDS, () => {
+            this._syncFormToStep();
+            this._updateOutput();
+            this._previewCurrentStep();
+        });
+    }
+
+    // ─── Event Delegation (Kompo $k or DOM fallback) ─────────────────
+
+    _setupEventDelegation() {
+        const listen = this._on || this._domOn.bind(this);
+
+        // Step list clicks
+        listen('click', '.sb-step-item', (event) => {
+            const el = (event.target || event).closest?.('.sb-step-item') || event.target;
+            const index = parseInt(el?.dataset?.index ?? el?.getAttribute?.('data-index'));
+            if (!isNaN(index)) this.selectStep(index);
+        });
+
+        // Option label changes
+        listen('input', '.sb-option-label', (event) => {
+            const el = event.target || event;
+            const idx = parseInt(el.dataset?.index);
+            const step = this.steps[this.selectedIndex];
+            if (step.options?.[idx]) {
+                step.options[idx].label = el.value;
+                this._updateOutput();
+            }
+        });
+
+        // Option action changes
+        listen('change', '.sb-option-action', (event) => {
+            const el = event.target || event;
+            const idx = parseInt(el.dataset?.index);
+            const step = this.steps[this.selectedIndex];
+            if (!step.options?.[idx]) return;
+            const opt = step.options[idx];
+            delete opt.done; delete opt.goToStep; delete opt.redirect;
+            switch (el.value) {
+                case 'done': opt.done = true; break;
+                case 'goToStep': opt.goToStep = this.selectedIndex + 1; break;
+                case 'redirect': opt.redirect = '/'; break;
+            }
+            this._updateOutput();
+        });
+
+        // Option removal
+        listen('click', '.sb-option-remove', (event) => {
+            const el = (event.target || event).closest?.('.sb-option-remove') || event.target;
+            const idx = parseInt(el?.dataset?.index);
+            const step = this.steps[this.selectedIndex];
+            if (step.options) {
+                step.options.splice(idx, 1);
+                if (!step.options.length) delete step.options;
+                this._renderOptions();
+                this._updateOutput();
+            }
+        });
+    }
+
+    /** DOM fallback for event delegation when $k.on is unavailable */
+    _domOn(event, selector, handler) {
+        const panel = document.getElementById('tutorial-step-builder');
+        if (!panel) return;
+        panel.addEventListener(event, (e) => {
+            const target = e.target.closest(selector);
+            if (target) handler(e);
+        });
+    }
+
+    // ─── Step Management ─────────────────────────────────────────────
+
+    selectStep(index) {
+        if (index < 0 || index >= this.steps.length) return;
+        this.selectedIndex = index;
+        this._syncStepToForm();
+        this._renderStepList();
+        this._renderOptions();
+        this._previewCurrentStep();
+    }
+
+    addStep() {
+        this.steps.push({ html: '', overlay: true, position: 'left', align: 'center' });
+        this.selectStep(this.steps.length - 1);
+    }
+
+    deleteStep() {
+        if (this.steps.length <= 1) return;
+        this.steps.splice(this.selectedIndex, 1);
+        this.selectStep(Math.min(this.selectedIndex, this.steps.length - 1));
+    }
+
+    duplicateStep() {
+        const clone = JSON.parse(JSON.stringify(this.steps[this.selectedIndex]));
+        this.steps.splice(this.selectedIndex + 1, 0, clone);
+        this.selectStep(this.selectedIndex + 1);
+    }
+
+    moveStepUp() {
+        if (this.selectedIndex <= 0) return;
+        const i = this.selectedIndex;
+        [this.steps[i - 1], this.steps[i]] = [this.steps[i], this.steps[i - 1]];
+        this.selectStep(i - 1);
+    }
+
+    moveStepDown() {
+        if (this.selectedIndex >= this.steps.length - 1) return;
+        const i = this.selectedIndex;
+        [this.steps[i], this.steps[i + 1]] = [this.steps[i + 1], this.steps[i]];
+        this.selectStep(i + 1);
+    }
+
+    // ─── Form ↔ Step Sync ────────────────────────────────────────────
+
+    _syncStepToForm() {
+        const step = this.steps[this.selectedIndex];
+        if (!step) return;
+        const f = this._field;
+
+        f('sb-html').set(step.html || '');
+        f('sb-overlay').set(step.overlay !== false);
+        f('sb-show-back').set(!!step.showBack);
+        f('sb-position').set(step.position || 'left');
+        f('sb-align').set(step.align || 'center');
+        f('sb-chat-mode').set(!!step.chatMode);
+        f('sb-position-target').set(step.positionTarget || '');
+
+        let advance = 'click';
+        if (step.autoNext) advance = 'auto';
+        else if (step.afterAnimation) advance = 'afterAnimation';
+        f('sb-advance').set(advance);
+        f('sb-auto-next-delay').set(typeof step.autoNext === 'number' ? step.autoNext : 3);
+
+        f('sb-silent-click').set(step.silentClick || '');
+        f('sb-redirect').set(step.redirect || '');
+        f('sb-show-if').set(step.showIf || '');
+
+        f('sb-cursor-from').set(step.cursor?.from || '');
+        f('sb-cursor-to').set(step.cursor?.to || '');
+        f('sb-cursor-duration').set(step.cursor?.duration || 1.5);
+        f('sb-cursor-click').set(!!step.cursor?.click);
+        f('sb-cursor-loop').set(!!step.cursor?.loop);
+
+        const hlElements = step.highlight?.groups?.flatMap(g => g.elements || g)?.join(', ') || '';
+        f('sb-highlight-elements').set(hlElements);
+        f('sb-highlight-mode').set(step.highlight?.mode || 'together');
+
+        f('sb-hover').set(Array.isArray(step.hover) ? step.hover.join(', ') : (step.hover || ''));
+        f('sb-scroll-to').set(step.scrollTo || '');
+        f('sb-scroll-inside-selector').set(step.scrollInside?.selector || '');
+        f('sb-scroll-inside-amount').set(step.scrollInside?.by || '');
+
+        this._updateOutput();
+    }
+
+    _syncFormToStep() {
+        const step = this.steps[this.selectedIndex];
+        if (!step) return;
+        const v = (name) => this._field(name).value;
+
+        step.html = v('sb-html');
+        step.overlay = v('sb-overlay');
+        if (v('sb-show-back')) step.showBack = true; else delete step.showBack;
+
+        step.position = v('sb-position') || 'left';
+        step.align = v('sb-align') || 'center';
+        if (v('sb-chat-mode')) step.chatMode = true; else delete step.chatMode;
+        const posTarget = v('sb-position-target');
+        if (posTarget) step.positionTarget = posTarget; else delete step.positionTarget;
+
+        const advance = v('sb-advance');
+        delete step.autoNext; delete step.afterAnimation;
+        if (advance === 'auto') step.autoNext = parseFloat(v('sb-auto-next-delay')) || 3;
+        else if (advance === 'afterAnimation') step.afterAnimation = true;
+
+        const sc = v('sb-silent-click');
+        if (sc) step.silentClick = sc; else delete step.silentClick;
+        const rd = v('sb-redirect');
+        if (rd) step.redirect = rd; else delete step.redirect;
+        const si = v('sb-show-if');
+        if (si) step.showIf = si; else delete step.showIf;
+
+        const cf = v('sb-cursor-from'), ct = v('sb-cursor-to');
+        if (cf || ct) {
+            step.cursor = step.cursor || {};
+            step.cursor.from = cf;
+            step.cursor.to = ct;
+            step.cursor.duration = parseFloat(v('sb-cursor-duration')) || 1.5;
+            step.cursor.click = !!v('sb-cursor-click');
+            step.cursor.loop = !!v('sb-cursor-loop');
+        } else { delete step.cursor; }
+
+        const hl = v('sb-highlight-elements');
+        if (hl) {
+            step.highlight = {
+                mode: v('sb-highlight-mode') || 'together',
+                groups: [{ elements: hl.split(',').map(s => s.trim()).filter(Boolean) }],
+            };
+        } else { delete step.highlight; }
+
+        const hv = v('sb-hover');
+        if (hv) {
+            const parts = hv.split(',').map(s => s.trim()).filter(Boolean);
+            step.hover = parts.length === 1 ? parts[0] : parts;
+        } else { delete step.hover; }
+
+        const st = v('sb-scroll-to');
+        if (st) step.scrollTo = st; else delete step.scrollTo;
+        const sis = v('sb-scroll-inside-selector');
+        if (sis) {
+            step.scrollInside = { selector: sis, by: parseFloat(v('sb-scroll-inside-amount')) || 0, duration: 1 };
+        } else { delete step.scrollInside; }
+    }
+
+    // ─── Dynamic Rendering ───────────────────────────────────────────
+
+    _renderStepList() {
+        const items = this.steps.map((step, i) => {
+            const active = i === this.selectedIndex;
+            const text = (step.html || step.silentClick || '').substring(0, 30);
+            const icons = [];
+            if (step.cursor) icons.push('\u2316');
+            if (step.highlight) icons.push('\u2606');
+            if (step.silentClick) icons.push('\u21B5');
+            if (step.options) icons.push('\u2026');
+
+            return `<div class="sb-step-item ${active ? 'sb-active' : ''}" data-index="${i}">
+                <span class="sb-step-num">${i}</span>
+                <span class="sb-step-text">${this._escapeHtml(text)}</span>
+                <span class="sb-step-icons">${icons.join('')}</span>
+            </div>`;
+        }).join('');
+
+        this._panel('step-builder-step-list').fill(`<div class="sb-step-list-inner">${items}</div>`);
+    }
+
+    _renderOptions() {
+        const step = this.steps[this.selectedIndex];
+        if (!step?.options?.length) {
+            this._panel('sb-options-editor').fill('');
+            return;
+        }
+
+        const html = step.options.map((opt, i) =>
+            `<div class="sb-option-row">
+                <input class="sb-option-input sb-option-label"
+                    value="${this._escapeHtml(opt.label || '')}" data-index="${i}" placeholder="Label">
+                <select class="sb-option-select sb-option-action" data-index="${i}">
+                    <option value="next" ${!opt.done && opt.goToStep === undefined && !opt.redirect ? 'selected' : ''}>Next</option>
+                    <option value="done" ${opt.done ? 'selected' : ''}>Done</option>
+                    <option value="goToStep" ${opt.goToStep !== undefined ? 'selected' : ''}>Go To Step</option>
+                    <option value="redirect" ${opt.redirect ? 'selected' : ''}>Redirect</option>
+                </select>
+                <button class="sb-option-remove" data-index="${i}">&times;</button>
+            </div>`
+        ).join('');
+
+        this._panel('sb-options-editor').fill(html);
+    }
+
+    _updateOutput() {
+        const outputEl = document.getElementById('sb-output');
+        if (!outputEl) return;
+        try {
+            outputEl.textContent = generateFullJson(this.steps, this.engine?.config);
+        } catch (e) {
+            outputEl.textContent = JSON.stringify(this.steps, null, 2);
+        }
+    }
+
+    // ─── Element Picker ──────────────────────────────────────────────
+
+    async pickElementFor(targetField) {
+        const selector = await pickElement();
+        if (selector) {
+            this._field(targetField).set(selector);
+            this._syncFormToStep();
+            this._updateOutput();
+            this._previewCurrentStep();
+        }
+    }
+
+    // ─── Clipboard ───────────────────────────────────────────────────
+
+    copyAll() {
+        let text;
+        try { text = generateFullJson(this.steps, this.engine?.config); }
+        catch (e) { text = JSON.stringify(this.steps, null, 2); }
+        this._copyText(text);
+    }
+
+    copyStep() {
+        this._copyText(JSON.stringify(this.steps[this.selectedIndex], null, 2));
+    }
+
+    _copyText(text) {
+        navigator.clipboard.writeText(text).catch(() => {
+            const ta = document.createElement('textarea');
+            ta.value = text;
+            ta.style.cssText = 'position:fixed;left:-9999px';
+            document.body.appendChild(ta);
+            ta.select();
+            document.execCommand('copy');
+            ta.remove();
+        });
+    }
+
+    // ─── Spectator Mode ──────────────────────────────────────────────
+
+    spectatorMode() {
+        const panelEl = document.getElementById('tutorial-step-builder');
+        if (panelEl) panelEl.style.display = 'none';
+
+        const exitBtn = document.createElement('button');
+        exitBtn.textContent = 'Exit Spectator (Esc)';
+        exitBtn.className = 'sb-spectator-exit';
+        exitBtn.onclick = exit;
+        document.body.appendChild(exitBtn);
+
+        const onEsc = (e) => { if (e.key === 'Escape') exit(); };
+        document.addEventListener('keydown', onEsc);
+
+        if (this.engine) { this.engine.steps = this.steps; this.engine.previewStep(0); }
+
+        const exit = () => {
+            if (panelEl) panelEl.style.display = '';
+            exitBtn.remove();
+            document.removeEventListener('keydown', onEsc);
+            this._previewCurrentStep();
+        };
+    }
+
+    // ─── Options ─────────────────────────────────────────────────────
+
+    addOption() {
+        const step = this.steps[this.selectedIndex];
+        step.options = step.options || [];
+        step.options.push({ label: 'New Option' });
+        this._renderOptions();
+        this._updateOutput();
+    }
+
+    // ─── Utilities ───────────────────────────────────────────────────
+
+    _escapeHtml(str) {
+        const div = document.createElement('div');
+        div.textContent = str;
+        return div.innerHTML;
+    }
+}