js-kompo-utils 1.0.0

package/tutorials/modules/Bubble.js

@@ -0,0 +1,617 @@
+import { computePosition, flip, shift, offset, arrow as arrowMiddleware, autoUpdate } from '@floating-ui/dom';
+
+const BUBBLE_PADDING = 'clamp(1rem, 3vw, 2rem) clamp(1.2rem, 4vw, 2.5rem)';
+
+export class Bubble {
+    constructor(engine) {
+        this.engine = engine;
+        this.el = null;
+        this.arrowEl = null;
+        this.textEl = null;
+        this.optionsRow = null;
+        this.btnRow = null;
+        this.actionBtn = null;
+        this.backBtn = null;
+        this.pauseBtn = null;
+        this._cleanupAutoUpdate = null;
+    }
+
+    create(config) {
+        if (this.el) this.destroy();
+
+        this.el = document.createElement('div');
+        this.el.id = 'tutorial-bubble';
+        this.el.className = 'tutorial-bubble';
+        this.el.setAttribute('role', 'status');
+        this.el.setAttribute('aria-live', 'polite');
+        this.el.style.maxWidth = config.bubbleMaxWidth;
+        this.el.style.minWidth = config.bubbleMinWidth;
+        this.el.style.fontSize = config.bubbleFontSize;
+        this.el.style.lineHeight = config.bubbleLineHeight;
+
+        this.arrowEl = document.createElement('div');
+        this.arrowEl.className = 'tutorial-arrow';
+        this.el.appendChild(this.arrowEl);
+
+        this.textEl = document.createElement('div');
+        this.textEl.id = 'tutorial-text';
+        this.textEl.className = 'tutorial-text';
+        this.el.appendChild(this.textEl);
+
+        this.optionsRow = document.createElement('div');
+        this.optionsRow.id = 'tutorial-options';
+        this.optionsRow.className = 'tutorial-options';
+        this.el.appendChild(this.optionsRow);
+
+        this.btnRow = document.createElement('div');
+        this.btnRow.className = 'tutorial-btn-row';
+
+        this.actionBtn = document.createElement('button');
+        this.actionBtn.className = 'tutorial-action-btn';
+        this.actionBtn.setAttribute('aria-label', 'Next step');
+
+        this.pauseBtn = document.createElement('button');
+        this.pauseBtn.textContent = '\u275A\u275A';
+        this.pauseBtn.className = 'tutorial-pause-btn';
+        this.pauseBtn.setAttribute('aria-label', 'Pause');
+
+        this.backBtn = document.createElement('button');
+        this.backBtn.textContent = '\u2190';
+        this.backBtn.className = 'tutorial-back-btn';
+        this.backBtn.setAttribute('aria-label', 'Previous step');
+
+        this.btnRow.appendChild(this.backBtn);
+        this.btnRow.appendChild(this.pauseBtn);
+        this.btnRow.appendChild(this.actionBtn);
+        this.el.appendChild(this.btnRow);
+
+        return {
+            el: this.el,
+            arrowEl: this.arrowEl,
+            textEl: this.textEl,
+            optionsRow: this.optionsRow,
+            btnRow: this.btnRow,
+            actionBtn: this.actionBtn,
+            backBtn: this.backBtn,
+            pauseBtn: this.pauseBtn,
+        };
+    }
+
+    getElement() { return this.el; }
+    getTextElement() { return this.textEl; }
+    getOptionsContainer() { return this.optionsRow; }
+
+    async positionForStep(step, refs, highlightBottom = false) {
+        const { overlay, container, img, imgWrapper, videoEl, isMobile, config } = refs;
+
+        this._stopAutoUpdate();
+
+        if (isMobile) {
+            this._positionMobile(step, highlightBottom, { overlay, container, img, imgWrapper, videoEl });
+            return;
+        }
+
+        this._resetDesktopOverrides({ container, img, imgWrapper, videoEl, config });
+
+        if (step.chatMode) {
+            this._positionDesktopChat(step, { overlay, container, config });
+            return;
+        }
+
+        await this._positionDesktopStandard(step, { overlay, container, img, imgWrapper, videoEl, config });
+    }
+
+    setChatMode(enabled, refs) {
+        if (!this.el) return;
+
+        let chatAvatarEl = this.el.querySelector('.tutorial-chat-avatar');
+
+        if (enabled) {
+            if (refs.img) refs.img.style.display = 'none';
+            if (refs.videoEl) refs.videoEl.style.display = 'none';
+            if (this.arrowEl) this.arrowEl.style.display = 'none';
+            if (this.textEl) this.textEl.style.minHeight = '0';
+
+            if (!chatAvatarEl && refs.img?.src) {
+                chatAvatarEl = document.createElement('div');
+                chatAvatarEl.className = 'tutorial-chat-avatar';
+                const chatImg = document.createElement('img');
+                chatImg.src = refs.img.src;
+                chatAvatarEl.appendChild(chatImg);
+                this.el.insertBefore(chatAvatarEl, this.arrowEl);
+            }
+            if (chatAvatarEl) chatAvatarEl.style.display = 'block';
+
+            this.el.className = 'tutorial-bubble tutorial-bubble--chat';
+            if (chatAvatarEl) {
+                chatAvatarEl.style.gridRow = '1 / -1';
+                chatAvatarEl.style.gridColumn = '1';
+            }
+            if (this.textEl) this.textEl.style.gridColumn = chatAvatarEl ? '2' : '';
+            if (this.optionsRow) this.optionsRow.style.gridColumn = chatAvatarEl ? '2' : '';
+            if (this.btnRow) this.btnRow.style.gridColumn = chatAvatarEl ? '2' : '';
+            if (this.arrowEl) this.arrowEl.style.gridColumn = '1 / -1';
+        } else {
+            if (refs.img) refs.img.style.display = 'block';
+            if (chatAvatarEl) chatAvatarEl.style.display = 'none';
+            this.el.className = 'tutorial-bubble';
+            if (this.textEl) this.textEl.style.gridColumn = '';
+            if (this.optionsRow) this.optionsRow.style.gridColumn = '';
+            if (this.btnRow) this.btnRow.style.gridColumn = '';
+            if (this.arrowEl) this.arrowEl.style.gridColumn = '';
+        }
+    }
+
+    clearStepContent() {
+        if (!this.el) return;
+        if (this.textEl) this.textEl.innerHTML = '';
+        if (this.optionsRow) {
+            this.optionsRow.innerHTML = '';
+            this.optionsRow.style.display = 'none';
+        }
+        if (this.btnRow) {
+            this.btnRow.style.opacity = '0';
+            this.btnRow.style.pointerEvents = 'none';
+        }
+    }
+
+    configureButtons(opts) {
+        if (this.actionBtn) {
+            this.actionBtn.textContent = opts.isLast ? opts.doneLabel : opts.nextLabel;
+            this.actionBtn.style.display = opts.hasOptions ? 'none' : '';
+        }
+        if (this.backBtn) {
+            this.backBtn.style.display =
+                (opts.showBack === true || typeof opts.showBack === 'number') ? '' : 'none';
+        }
+    }
+
+    revealButtons() {
+        if (!this.btnRow) return;
+        this.btnRow.style.opacity = '1';
+        this.btnRow.style.pointerEvents = 'auto';
+    }
+
+    show() {
+        if (!this.el) return;
+        this.el.style.opacity = '1';
+        // Preserve translate(-50%,-50%) if centered, just remove scale
+        const current = this.el.style.transform;
+        if (current.includes('translate')) {
+            this.el.style.transform = current.replace(/scale\([^)]*\)/, '').trim() || 'none';
+        } else {
+            this.el.style.transform = 'scale(1)';
+        }
+    }
+
+    hide() {
+        if (!this.el) return Promise.resolve();
+        this._stopAutoUpdate();
+        this.el.style.opacity = '0';
+        this.el.style.transform = 'scale(0.8)';
+        return new Promise(resolve => setTimeout(resolve, 300));
+    }
+
+    setContent(html) {
+        if (this.textEl) {
+            this.textEl.innerHTML = html;
+        }
+    }
+
+    destroy() {
+        this._stopAutoUpdate();
+        this.el?.remove();
+        this.el = null;
+        this.arrowEl = null;
+        this.textEl = null;
+        this.optionsRow = null;
+        this.btnRow = null;
+        this.actionBtn = null;
+        this.backBtn = null;
+        this.pauseBtn = null;
+    }
+
+    // --- Private: mobile positioning (CSS flexbox, no @floating-ui) ---
+
+    _positionMobile(step, highlightBottom, refs) {
+        const { overlay, container, img, imgWrapper, videoEl } = refs;
+
+        if (container) {
+            container.style.alignItems = 'center';
+            container.style.flexDirection = 'row';
+        }
+
+        if (imgWrapper) {
+            Object.assign(imgWrapper.style, {
+                display: 'flex',
+                flexDirection: 'column',
+                alignItems: 'center',
+                width: '100%',
+            });
+        }
+
+        if (img) {
+            Object.assign(img.style, {
+                height: 'clamp(120px, 30vh, 240px)',
+                maxHeight: '30vh',
+                alignSelf: 'center',
+            });
+        }
+        if (videoEl) {
+            videoEl.style.height = 'clamp(120px, 30vh, 240px)';
+            videoEl.style.maxHeight = '30vh';
+        }
+
+        if (!this.el) return;
+
+        this.el.className = 'tutorial-bubble tutorial-bubble--mobile';
+        if (this.textEl) this.textEl.style.minHeight = '80px';
+        if (this.arrowEl) this.arrowEl.className = 'tutorial-arrow tutorial-arrow--hidden';
+
+        if (overlay) {
+            overlay.style.justifyContent = 'center';
+            overlay.style.padding = '8px';
+        }
+
+        if (highlightBottom) {
+            if (overlay) {
+                overlay.style.alignItems = 'flex-start';
+                overlay.style.paddingTop = 'max(8px, env(safe-area-inset-top))';
+                overlay.style.paddingBottom = '8px';
+            }
+            if (this.el) {
+                this.el.style.order = '2';
+                this.el.style.marginTop = '8px';
+                this.el.style.marginBottom = '0';
+                this.el.style.transformOrigin = 'top center';
+            }
+
+            if (img) { img.style.transform = 'scaleY(-1)'; img.style.order = '1'; }
+            if (videoEl) { videoEl.style.transform = 'scaleY(-1)'; videoEl.style.order = '1'; }
+        } else {
+            if (overlay) {
+                overlay.style.alignItems = 'flex-end';
+                overlay.style.paddingTop = '8px';
+                overlay.style.paddingBottom = 'max(8px, env(safe-area-inset-bottom))';
+            }
+            if (this.el) {
+                this.el.style.order = '1';
+                this.el.style.marginBottom = '8px';
+                this.el.style.marginTop = '0';
+                this.el.style.transformOrigin = 'bottom center';
+            }
+
+            if (img) { img.style.transform = 'none'; img.style.order = '3'; }
+            if (videoEl) { videoEl.style.transform = 'none'; videoEl.style.order = '3'; }
+        }
+    }
+
+    // --- Private: desktop resets ---
+
+    _resetDesktopOverrides(refs) {
+        const { container, img, imgWrapper, videoEl, config } = refs;
+
+        // Reset container flex from previous step's align/chat positioning
+        if (container) {
+            container.style.justifyContent = '';
+            container.style.alignItems = '';
+            container.style.flexDirection = '';
+            container.style.padding = '';
+            container.style.overflow = '';
+            container.style.position = '';
+        }
+
+        if (imgWrapper) {
+            Object.assign(imgWrapper.style, {
+                display: '',
+                flexDirection: '',
+                alignItems: '',
+                width: '',
+            });
+        }
+
+        if (img) {
+            img.style.transform = 'none';
+            img.style.order = '';
+            img.style.alignSelf = '';
+            img.style.height = config.avatarHeight || '';
+            img.style.maxHeight = config.avatarMaxHeight || '';
+        }
+
+        if (this.el) {
+            this.el.style.order = '';
+            this.el.style.width = '';
+            this.el.style.alignSelf = '';
+        }
+
+        if (videoEl) {
+            videoEl.style.transform = 'none';
+            videoEl.style.order = '';
+            videoEl.style.height = config.avatarHeight || '';
+            videoEl.style.maxHeight = config.avatarMaxHeight || '';
+        }
+    }
+
+    // --- Private: desktop chat positioning (relative, no @floating-ui) ---
+
+    _positionDesktopChat(step, refs) {
+        const { overlay, container, config } = refs;
+        const side = step.position || 'left';
+        const align = step.align || 'center';
+
+        this.positionChat({
+            chatMaxWidth: step.chatMaxWidth,
+            positionTarget: step.positionTarget,
+            side,
+            align,
+            config,
+            refs: { overlay, container },
+        });
+
+        if (step.positionTarget) {
+            this._startChatAutoUpdate(container, step.positionTarget, side);
+        }
+    }
+
+    positionChat(options = {}) {
+        if (!this.el) return;
+
+        const config = options.config || {};
+        const overlay = options.refs?.overlay;
+        const container = options.refs?.container;
+        const side = options.side;
+        const align = options.align;
+
+        this.el.className = 'tutorial-bubble tutorial-bubble--chat';
+        // Reset standard mode positioning — chat uses its own layout
+        this.el.style.position = 'fixed';
+        this.el.style.left = '50%';
+        this.el.style.top = '50%';
+        this.el.style.transform = 'translate(-50%, -50%)';
+        this.el.style.right = 'auto';
+        this.el.style.bottom = 'auto';
+        this.el.style.marginRight = '0';
+        this.el.style.marginLeft = '0';
+        this.el.style.padding = BUBBLE_PADDING;
+        this.el.style.fontSize = config.bubbleFontSize || '';
+        this.el.style.maxWidth = options.chatMaxWidth || config.bubbleMaxWidth || 'clamp(260px, 85vw, 550px)';
+        this.el.style.minWidth = config.bubbleMinWidth || 'clamp(200px, 70vw, 350px)';
+
+        if (this.textEl) this.textEl.style.minHeight = '0';
+        if (this.arrowEl) this.arrowEl.className = 'tutorial-arrow tutorial-arrow--hidden';
+
+        if (container) {
+            container.style.alignItems = 'stretch';
+            container.style.overflow = '';
+        }
+
+        if (overlay) {
+            overlay.style.padding = '0';
+        }
+
+        if (options.positionTarget) {
+            if (container) {
+                this._positionAtTarget(container, options.positionTarget, side);
+
+                if (options.chatMaxWidth) {
+                    this.el.style.maxWidth = options.chatMaxWidth;
+                    this.el.style.minWidth = 'auto';
+                }
+
+                this.el.style.overflowWrap = 'break-word';
+                this.el.style.wordBreak = 'break-word';
+                this.el.style.boxSizing = 'border-box';
+
+                if (overlay) {
+                    overlay.style.justifyContent = '';
+                    overlay.style.alignItems = '';
+                }
+
+                container.style.maxWidth = '';
+            }
+        } else {
+            if (container) {
+                this._resetContainerPosition(container);
+
+                const vMap = { top: 'flex-start', bottom: 'flex-end' };
+                const hMap = { left: 'flex-start', center: 'center', right: 'flex-end' };
+
+                container.style.alignItems = vMap[side] || 'center';
+                container.style.justifyContent = hMap[align] || 'center';
+                container.style.padding = '16px';
+            }
+        }
+    }
+
+    // --- Private: standard desktop positioning via @floating-ui ---
+
+    async _positionDesktopStandard(step, refs) {
+        const { overlay, container, img, videoEl, config } = refs;
+        const side = step.position || 'left';
+        const align = step.align || 'center';
+
+        if (!this.el) return;
+
+        // Move avatar to the align position (left/center/right of screen)
+        if (container) {
+            const alignMap = { left: 'flex-start', center: 'center', right: 'flex-end' };
+            container.style.justifyContent = alignMap[align] || 'center';
+        }
+
+        // Apply per-step avatar size override
+        if (step.avatarSize && img) {
+            img.style.height = step.avatarSize;
+            img.style.maxHeight = step.avatarSize;
+        }
+
+        // Custom position mode: manual left/top values, no floating-ui
+        if (side === 'custom') {
+            this._stopAutoUpdate();
+            this.el.style.position = 'fixed';
+            this.el.style.left = step.bubbleLeft || '50%';
+            this.el.style.top = step.bubbleTop || '50%';
+            this.el.style.transform = (!step.bubbleLeft && !step.bubbleTop) ? 'translate(-50%, -50%)' : '';
+            this.el.style.right = 'auto';
+            this.el.style.bottom = 'auto';
+            this.el.style.padding = BUBBLE_PADDING;
+            this.el.style.fontSize = config.bubbleFontSize;
+            this.el.style.maxWidth = config.bubbleMaxWidth;
+            this.el.style.minWidth = config.bubbleMinWidth;
+            if (this.arrowEl) this.arrowEl.style.display = 'none';
+            return;
+        }
+
+        const referenceEl = step.positionTarget
+            ? document.querySelector(step.positionTarget)
+            : (videoEl && videoEl.style.display !== 'none' ? videoEl : img);
+
+        // No reference element — center the bubble on screen
+        if (!referenceEl) {
+            this.el.style.position = 'fixed';
+            this.el.style.left = '50%';
+            this.el.style.top = '50%';
+            this.el.style.transform = 'translate(-50%, -50%)';
+            this.el.style.padding = BUBBLE_PADDING;
+            this.el.style.fontSize = config.bubbleFontSize;
+            this.el.style.maxWidth = config.bubbleMaxWidth;
+            this.el.style.minWidth = config.bubbleMinWidth;
+            if (this.arrowEl) this.arrowEl.style.display = 'none';
+            return;
+        }
+
+        // Bubble is fixed on body — floating-ui viewport coordinates map directly
+        this.el.style.position = 'fixed';
+        this.el.style.left = 'auto';
+        this.el.style.top = 'auto';
+        this.el.style.transform = '';
+        this.el.style.padding = BUBBLE_PADDING;
+        this.el.style.fontSize = config.bubbleFontSize;
+        this.el.style.maxWidth = config.bubbleMaxWidth;
+        this.el.style.minWidth = config.bubbleMinWidth;
+
+        if (this.textEl) this.textEl.style.minHeight = '0';
+        if (this.arrowEl) this.arrowEl.style.display = '';
+
+        const runPosition = async () => {
+            if (!this.el) return;
+
+            const { x, y, placement, middlewareData } = await computePosition(
+                referenceEl, this.el, {
+                    placement: side,
+                    middleware: [
+                        offset(15),
+                        flip(),
+                        shift({ padding: 8 }),
+                        arrowMiddleware({ element: this.arrowEl, padding: 14 }),
+                    ],
+                }
+            );
+
+            Object.assign(this.el.style, {
+                left: `${x}px`,
+                top: `${y}px`,
+                right: 'auto',
+                bottom: 'auto',
+                marginLeft: '0',
+                marginRight: '0',
+            });
+
+            const basePlacement = placement.split('-')[0];
+            if (this.arrowEl) {
+                this.arrowEl.className = `tutorial-arrow tutorial-arrow--${basePlacement}`;
+
+                // Reset inline arrow position before applying middleware values
+                this.arrowEl.style.left = '';
+                this.arrowEl.style.top = '';
+                this.arrowEl.style.right = '';
+                this.arrowEl.style.bottom = '';
+
+                if (middlewareData.arrow) {
+                    const { x: ax, y: ay } = middlewareData.arrow;
+                    if (ax != null) this.arrowEl.style.left = `${ax}px`;
+                    if (ay != null) this.arrowEl.style.top = `${ay}px`;
+                }
+            }
+
+            // Set transform-origin based on resolved placement
+            const originMap = {
+                left: 'bottom right',
+                right: 'bottom left',
+                top: 'bottom center',
+                bottom: 'top center',
+            };
+            this.el.style.transformOrigin = originMap[basePlacement] || 'bottom right';
+        };
+
+        await runPosition();
+
+        this._stopAutoUpdate();
+        this._cleanupAutoUpdate = autoUpdate(referenceEl, this.el, runPosition);
+    }
+
+    // --- Private: position container at target via @floating-ui ---
+
+    async _positionAtTarget(container, targetSelector, side) {
+        if (!container) return;
+        const target = document.querySelector(targetSelector);
+        if (!target) {
+            this._resetContainerPosition(container);
+            return;
+        }
+
+        container.style.position = 'fixed';
+
+        const { x, y } = await computePosition(target, container, {
+            placement: side || 'left',
+            middleware: [
+                offset(10),
+                flip(),
+                shift({ padding: 8 }),
+            ],
+        });
+
+        Object.assign(container.style, {
+            left: `${x}px`,
+            top: `${y}px`,
+            bottom: 'auto',
+            right: 'auto',
+            transform: 'none',
+            maxHeight: `${window.innerHeight - 16}px`,
+            overflow: 'auto',
+        });
+    }
+
+    // --- Private: auto-update for chat mode with positionTarget ---
+
+    _startChatAutoUpdate(container, targetSelector, side) {
+        if (!container) return;
+        const target = document.querySelector(targetSelector);
+        if (!target) return;
+
+        this._stopAutoUpdate();
+        this._cleanupAutoUpdate = autoUpdate(target, container, () => {
+            this._positionAtTarget(container, targetSelector, side);
+        });
+    }
+
+    _resetContainerPosition(container) {
+        if (!container) return;
+        Object.assign(container.style, {
+            position: '',
+            left: '',
+            right: '',
+            top: '',
+            bottom: '',
+            transform: '',
+            maxHeight: '',
+            overflow: '',
+        });
+    }
+
+    _stopAutoUpdate() {
+        if (this._cleanupAutoUpdate) {
+            this._cleanupAutoUpdate();
+            this._cleanupAutoUpdate = null;
+        }
+    }
+}