lumina-slides 8.9.4 → 9.0.0

package/src/composables/useLumina.ts

@@ -0,0 +1,32 @@
+import { computed, inject } from 'vue';
+import { StoreKey } from '../core/store';
+
+/**
+ * LUMINA COMPOSABLE
+ * 
+ * The primary way for Vue components (Slides, Layouts) to interact with the Engine.
+ * Provides typesafe access to state, getters, and actions.
+ * 
+ * @throws Error if used outside of a <LuminaDeck> context (Dependency Injection).
+ * @returns {Object} { slide, index, total, next, prev, goto, options }
+ */
+export function useLumina() {
+    const store = inject(StoreKey);
+
+    if (!store) {
+        throw new Error("Lumina: Component must be used within a Lumina instance.");
+    }
+
+    return {
+        // State
+        slide: computed(() => store.currentSlide()),
+        index: computed(() => store.state.currentIndex),
+        total: computed(() => store.state.deck?.slides.length || 0),
+
+        // Actions
+        next: store.next,
+        prev: store.prev,
+        goto: store.goto,
+        options: store.state.options
+    };
+}

package/src/composables/useStudio.ts

@@ -0,0 +1,87 @@
+import { reactive, computed, inject, InjectionKey } from 'vue';
+import { StoreKey } from '../core/store';
+import { bus } from '../core/events';
+
+export const StudioKey: InjectionKey<ReturnType<typeof createStudio>> = Symbol('StudioKey');
+
+export function createStudio() {
+    const store = inject(StoreKey);
+    if (!store) {
+        throw new Error("Lumina Studio requires Lumina Store.");
+    }
+
+    const state = reactive({
+        isEnabled: false,
+        selectedElementPath: null as string | null,
+        selectedElementSchema: null as string | null, // 'title', 'image', etc.
+        selectionRect: null as DOMRect | null,
+    });
+
+    const toggle = () => {
+        state.isEnabled = !state.isEnabled;
+        if (!state.isEnabled) {
+            clearSelection();
+        }
+    };
+
+    const selectElement = (path: string, schema: string, rect?: DOMRect) => {
+        if (!state.isEnabled) return;
+        state.selectedElementPath = path;
+        state.selectedElementSchema = schema;
+        if (rect) state.selectionRect = rect;
+    };
+
+    const clearSelection = () => {
+        state.selectedElementPath = null;
+        state.selectedElementSchema = null;
+        state.selectionRect = null;
+    };
+
+    const currentSlide = computed(() => store.currentSlide());
+
+    // Helper to get nested value by path string "elements.0.title"
+    const getValueByPath = (obj: any, path: string) => {
+        return path.split('.').reduce((acc, part) => acc && acc[part], obj);
+    };
+
+    const selectedData = computed(() => {
+        if (!state.selectedElementPath || !currentSlide.value) return null;
+        // If path is empty or 'root', return slide itself
+        if (state.selectedElementPath === 'root') return currentSlide.value;
+        return getValueByPath(currentSlide.value, state.selectedElementPath);
+    });
+
+    const updateSelected = (payload: any) => {
+        if (!state.selectedElementPath || !store.state.deck) return;
+
+        const slideIndex = store.state.currentIndex;
+        // If path is 'root', we are updating the slide itself
+        const relativePath = state.selectedElementPath === 'root' ? '' : '.' + state.selectedElementPath;
+        const fullPath = `slides.${slideIndex}${relativePath}`;
+
+        // Update the store directly
+        if (store.updateNode) {
+            store.updateNode(fullPath, payload);
+        }
+
+        // Also emit for external listeners if needed
+        bus.emit('studio:update', { path: fullPath, value: payload });
+    };
+
+    return {
+        state,
+        toggle,
+        selectElement,
+        clearSelection,
+        selectedData,
+        updateSelected
+    };
+}
+
+export function useStudio() {
+    const studio = inject(StudioKey);
+    if (!studio) {
+        throw new Error("useStudio must be used within LuminaStudio");
+    }
+    return studio;
+}

package/src/composables/useSwipeNav.ts

@@ -0,0 +1,53 @@
+import { ref, inject } from 'vue';
+import { StoreKey } from '../core/store';
+
+const SWIPE_THRESHOLD = 50;
+const SWIPE_HORIZONTAL_RATIO = 1.5;
+const THROTTLE_MS = 400;
+
+/**
+ * Touch swipe to navigate between slides on mobile.
+ * Swipe left -> next, swipe right -> prev.
+ * Only triggers when the gesture is clearly horizontal (avoids conflict with vertical scroll).
+ */
+export function useSwipeNav() {
+    const store = inject(StoreKey);
+    if (!store) return { onTouchStart: () => {}, onTouchEnd: () => {} };
+
+    const touchStart = ref<{ x: number; y: number } | null>(null);
+    let lastSwipeTime = 0;
+
+    const onTouchStart = (e: TouchEvent) => {
+        if (e.touches.length !== 1) return;
+        touchStart.value = { x: e.touches[0].clientX, y: e.touches[0].clientY };
+    };
+
+    const onTouchEnd = (e: TouchEvent) => {
+        const start = touchStart.value;
+        touchStart.value = null;
+        if (!start || e.changedTouches.length !== 1) return;
+
+        const { options } = store.state;
+        if (!options.navigation) return;
+
+        const now = Date.now();
+        if (now - lastSwipeTime < THROTTLE_MS) return;
+
+        const end = e.changedTouches[0];
+        const dx = end.clientX - start.x;
+        const dy = end.clientY - start.y;
+
+        if (Math.abs(dx) < SWIPE_THRESHOLD) return;
+        if (Math.abs(dx) <= Math.abs(dy) * SWIPE_HORIZONTAL_RATIO) return;
+
+        if (dx < 0 && store.hasNext()) {
+            store.next();
+            lastSwipeTime = now;
+        } else if (dx > 0 && store.hasPrev()) {
+            store.prev();
+            lastSwipeTime = now;
+        }
+    };
+
+    return { onTouchStart, onTouchEnd };
+}

package/src/composables/useTransition.ts

@@ -0,0 +1,373 @@
+import { onMounted, onUnmounted, nextTick, inject, watch, type Ref } from 'vue';
+import gsap from 'gsap';
+import { StoreKey } from '../core/store';
+import { resolveTransitionConfig } from '../core/animationConfig';
+import type { BaseSlideData } from '../core/types';
+
+/**
+ * REUSABLE TRANSITION SYSTEM
+ * 
+ * Automatically applies entrance animations to elements with 'reveal-*' classes.
+ * Reads configuration from the store, prioritizing slide-level then deck-level meta.
+ * 
+ * @param containerRef - Vue Ref pointing to the slide's root element.
+ * @param slideData - Optional slide-specific data for local overrides.
+ * @param onComplete - Optional callback fired when the entrance animation finishes.
+ */
+/** True if container itself or any [data-lumina-id] descendant has elementState.visible === false. */
+function hasElementControlledHiddenDescendant(
+    container: Element,
+    elementState: Record<string, { visible?: boolean }>
+): boolean {
+    const selfId = container.getAttribute?.('data-lumina-id');
+    if (selfId && elementState[selfId]?.visible === false) return true;
+    const nodes = container.querySelectorAll?.('[data-lumina-id]') || [];
+    for (const el of nodes) {
+        const id = el.getAttribute('data-lumina-id');
+        if (id && elementState[id]?.visible === false) return true;
+    }
+    return false;
+}
+
+export function useTransition(containerRef: Ref<HTMLElement | null>, slideData?: BaseSlideData, onComplete?: () => void) {
+    const store = inject(StoreKey);
+    let ctx: gsap.Context | null = null;
+
+    // Helper: Manually split text into spans for character/word animation
+    const splitText = (elements: NodeListOf<Element> | Element[]) => {
+        // Restore elements that are no longer intended for split text
+        containerRef.value?.querySelectorAll('[data-split-init]').forEach(el => {
+            const element = el as HTMLElement;
+            if (!element.hasAttribute('data-split-text')) {
+                element.innerHTML = element.dataset.splitTextValue || element.innerText;
+                delete element.dataset.splitInit;
+                delete element.dataset.splitTextValue;
+            }
+        });
+
+        elements.forEach(el => {
+            const element = el as HTMLElement;
+            const text = element.innerText;
+            if (!text) return;
+
+            // If text changed, re-split
+            if (element.dataset.splitTextValue === text) return;
+
+            element.innerHTML = text.split('').map(char =>
+                char === ' ' ? '&nbsp;' : `<span class="inline-block reveal-char">${char}</span>`
+            ).join('');
+
+            element.dataset.splitInit = 'true';
+            element.dataset.splitTextValue = text;
+            element.style.whiteSpace = 'normal';
+        });
+    };
+
+    const animateIn = (immediate = false) => {
+        if (!containerRef.value) return;
+
+        ctx?.revert();
+
+        const config = resolveTransitionConfig(store, slideData);
+        const { enabled, type, entranceReveal } = config;
+
+        // Initial Properties
+        const isFlip = type === 'flip';
+        const isZoomRotate = type === 'zoom-rotate';
+        const isElastic = type === 'elastic-up';
+        const isBlur = type === 'blur';
+        const isSkew = type === 'skew';
+        const isSpring = type === 'spring' || isElastic;
+
+        // 1. NO REVEAL TIMELINE: when entranceReveal is off (default), animations disabled, or immediate
+        // The built-in GSAP reveal on .reveal-* runs only when meta.effects.entranceReveal or
+        // options.animation.entranceReveal is explicitly true. Otherwise we only set final state
+        // (excluded=opacity 0, toReveal=opacity 1) for any .reveal-* present; no stagger/timeline.
+        if (enabled === false || immediate || !entranceReveal) {
+            const allPossible = [
+                '.reveal-up', '.reveal-zoom', '.reveal-card', '.reveal-left', '.reveal-right',
+                '.reveal-content > *',
+                '.flex-layout > div > *',
+                '.reveal-img', '.reveal-char', '[data-split-text]', '.reveal-child'
+            ].join(', ');
+
+            // Should also process split text if needed for immediate display
+            const textToSplit = containerRef.value.querySelectorAll('[data-split-text]');
+            if (textToSplit.length) splitText(textToSplit);
+
+            const es = store?.state?.elementState ?? {};
+            const allEls = Array.from(containerRef.value.querySelectorAll(allPossible));
+            const toReveal = allEls.filter(e => !hasElementControlledHiddenDescendant(e, es));
+            const excluded = allEls.filter(e => hasElementControlledHiddenDescendant(e, es));
+            gsap.set(excluded, { opacity: 0 });
+            gsap.set(toReveal, {
+                opacity: 1, y: 0, x: 0, scale: 1, filter: 'blur(0px)', visibility: 'visible', rotation: 0, rotationY: 0, skewY: 0
+            });
+
+            // Ensure split text chars are visible
+            const chars = containerRef.value.querySelectorAll('.reveal-char');
+            if (chars.length) {
+                gsap.set(chars, { y: '0%', opacity: 1, rotateX: 0 });
+            }
+
+            return;
+        }
+
+        // 2. ANIMATION CONTEXT
+        ctx = gsap.context(() => {
+            const el = containerRef.value!;
+
+            // 1. Handle Text Splitting FIRST
+            const textToSplit = el.querySelectorAll('[data-split-text]');
+            if (textToSplit.length) splitText(textToSplit);
+
+            // Initial Properties
+            const initY = (type === 'fade' || isBlur || isFlip) ? 0 : (isElastic ? 100 : 30);
+            const initRotationY = isFlip ? 90 : 0;
+            const initRotation = isZoomRotate ? -10 : 0;
+            const initScale = (type === 'zoom' || isZoomRotate) ? 0.7 : 1;
+            const initBlur = isBlur ? 15 : 0;
+            const initSkew = isSkew ? 10 : 0;
+
+            // Set Initial States
+            const standardSelector = [
+                '.reveal-up', '.reveal-zoom', '.reveal-card', '.reveal-left', '.reveal-right',
+                '.reveal-content > *',
+                '.flex-layout > div > *'
+            ].join(', ');
+
+            const es = store?.state?.elementState ?? {};
+            const raw = Array.from(el.querySelectorAll(standardSelector)).filter(item => !item.hasAttribute('data-split-text'));
+            const standardElements = raw.filter(item => !hasElementControlledHiddenDescendant(item, es)) as HTMLElement[];
+            const excluded = raw.filter(item => hasElementControlledHiddenDescendant(item, es));
+            if (excluded.length) {
+                gsap.set(excluded, { opacity: 0 });
+            }
+
+            const chars = el.querySelectorAll('.reveal-char');
+            const images = el.querySelectorAll('.reveal-img');
+            const childReveals = el.querySelectorAll('.reveal-child');
+
+            // Ensure split-text containers themselves are visible (spans will handle the staggering)
+            if (textToSplit.length) {
+                gsap.set(textToSplit, { opacity: 1, visibility: 'visible' });
+            }
+
+            // Apply Initial States for standard elements
+            if (standardElements.length) {
+                gsap.set(standardElements, {
+                    y: initY,
+                    opacity: 0,
+                    scale: initScale,
+                    rotationY: initRotationY,
+                    rotation: initRotation,
+                    filter: `blur(${initBlur}px)`,
+                    skewY: initSkew,
+                    transformPerspective: 1200
+                });
+
+                // Directional Overrides
+                const lefts = standardElements.filter(e => e.classList.contains('reveal-left'));
+                const rights = standardElements.filter(e => e.classList.contains('reveal-right'));
+                if (lefts.length > 0) gsap.set(lefts, { x: -50, y: 0 });
+                if (rights.length > 0) gsap.set(rights, { x: 50, y: 0 });
+            }
+
+            if (images.length) {
+                gsap.set(images, { scale: 1.1, opacity: 0, filter: 'blur(10px)' });
+            }
+            if (chars.length) {
+                gsap.set(chars, { y: '100%', opacity: 0, rotateX: -90 });
+            }
+            if (childReveals.length) {
+                gsap.set(childReveals, { y: 15, opacity: 0 });
+            }
+
+            // Timeline
+            const dIn = config.durationIn || (isElastic ? config.durationInElastic : config.durationInStandard);
+            const tl = gsap.timeline({
+                defaults: {
+                    ease: config.ease || (isElastic ? config.easeElastic : (isSpring ? config.easeSpring : config.ease)),
+                    duration: dIn
+                },
+                onComplete
+            });
+
+            // Start Animation Sequence
+            // ------------------------
+
+            // 1. Images
+            if (images.length) {
+                tl.to(images, {
+                    scale: 1, opacity: 1, filter: 'blur(0px)',
+                    duration: dIn * config.imageDurationMultiplier,
+                    ease: config.imageEase
+                }, 0);
+            }
+
+            // 2. Characters (Text)
+            if (chars.length) {
+                tl.to(chars, {
+                    y: '0%', opacity: 1, rotateX: 0,
+                    duration: dIn * config.characterDurationFactor,
+                    stagger: config.characterStagger,
+                    ease: config.characterEase
+                }, 0.05);
+            }
+
+            // 3. Standard Elements (Staggered)
+            if (standardElements.length) {
+                tl.to(standardElements, {
+                    y: 0, x: 0, opacity: 1, scale: 1,
+                    rotationY: 0, rotation: 0,
+                    filter: 'blur(0px)',
+                    skewY: 0,
+                    duration: dIn,
+                    stagger: config.stagger
+                }, 0.1);
+            }
+
+            // 4. Reveal Children (Micro-stagger inside cards)
+            if (childReveals.length) {
+                tl.to(childReveals, {
+                    y: 0, opacity: 1,
+                    duration: dIn * config.childRevealDurationFactor,
+                    stagger: config.childRevealStagger,
+                    ease: config.childRevealEase
+                }, config.childRevealStart);
+            }
+
+        }, containerRef.value);
+    };
+
+    const animateOut = (): Promise<void> => {
+        return new Promise((resolve) => {
+            if (!containerRef.value) { resolve(); return; }
+
+            const config = resolveTransitionConfig(store, slideData);
+            const { enabled, type, durationOut, stagger } = config;
+
+            if (enabled === false) { resolve(); return; }
+
+            const el = containerRef.value;
+            const standardReveals = [
+                '.reveal-up', '.reveal-zoom', '.reveal-card', '.reveal-left', '.reveal-right',
+                '.reveal-content > *',
+                '.flex-layout > div > *',
+            ].join(', ');
+            const elements = el.querySelectorAll(standardReveals);
+            const chars = el.querySelectorAll('.reveal-char');
+            const childReveals = el.querySelectorAll('.reveal-child');
+            const img = el.querySelector('.reveal-img');
+
+            const tl = gsap.timeline({
+                onComplete: resolve,
+                defaults: {
+                    duration: durationOut,
+                    ease: config.easeOut
+                }
+            });
+
+            // Exit Sequence (Reverse of Entry)
+            // -------------------------------
+
+            // 1. Elements
+            if (elements.length) {
+                const moveY = (type === 'fade' || type === 'blur') ? 0 : (type === 'cascade' ? -30 : 20);
+                tl.to(elements, {
+                    opacity: 0,
+                    y: moveY,
+                    scale: type === 'zoom' ? 0.9 : 1,
+                    stagger: stagger * config.exitStaggerFactor
+                }, 0);
+            }
+
+            // 2. Characters
+            if (chars.length) {
+                const charY = type === 'fade' ? 0 : '-50%';
+                tl.to(chars, {
+                    opacity: 0,
+                    y: charY,
+                    stagger: config.exitCharStagger,
+                    ease: config.easeOut
+                }, 0.1);
+            }
+
+            // 3. Image
+            if (img) {
+                tl.to(img, {
+                    opacity: 0,
+                    scale: 1.05,
+                    filter: 'blur(10px)',
+                    duration: durationOut * config.exitImageDurationFactor
+                }, 0.1);
+            }
+
+            if (childReveals.length) {
+                tl.to(childReveals, { opacity: 0, y: 10, duration: durationOut * config.exitChildDurationFactor }, 0);
+            }
+
+            // Fallback if no elements were found, ensure resolve is called
+            if (!elements.length && !chars.length && !img) {
+                resolve();
+            }
+        });
+    };
+
+    // Live Update Watcher (for Studio)
+    watch(() => ([
+        slideData,
+        store?.state.deck?.meta?.effects,
+        store?.state.options.animation
+    ]), () => {
+        nextTick(() => animateIn(true)); // Pass true for immediate update
+    }, { deep: true });
+
+    onMounted(() => {
+        // Initial trigger
+        animateIn();
+
+        // Watch for async content appearing (e.g. Charts after loading)
+        const observer = new MutationObserver(() => {
+            const el = containerRef.value;
+            if (!el) return;
+
+            const config = resolveTransitionConfig(store, slideData);
+
+            // If animations are DISABLED or entranceReveal is off, only set final state for late-appearing items (e.g. charts)
+            if (config.enabled === false || !config.entranceReveal) {
+                const allPossible = [
+                    '.reveal-up', '.reveal-zoom', '.reveal-card', '.reveal-left', '.reveal-right',
+                    '.reveal-content > *', '.flex-layout > div > *',
+                    '.reveal-img', '.reveal-char', '[data-split-text]', '.reveal-child'
+                ].join(', ');
+                const es = store?.state?.elementState ?? {};
+                const raw = Array.from(el.querySelectorAll(allPossible));
+                const items = raw.filter(e => !hasElementControlledHiddenDescendant(e, es));
+                const excluded = raw.filter(e => hasElementControlledHiddenDescendant(e, es));
+                if (excluded.length) gsap.set(excluded, { opacity: 0 });
+                if (items.length) {
+                    gsap.set(items, { opacity: 1, y: 0, x: 0, scale: 1, filter: 'blur(0px)', visibility: 'visible' });
+                }
+                return;
+            }
+
+            // If entranceReveal is ON, check for revealable elements that haven't been animated yet
+            if (config.entranceReveal) {
+                const lateElements = el.querySelectorAll('.reveal-up, .reveal-zoom, .reveal-card, .reveal-left, .reveal-right, .reveal-content > *, .flex-layout > div > *');
+                const hasInvisible = Array.from(lateElements).some(e => (e as HTMLElement).style.opacity === '' && getComputedStyle(e).opacity === '0');
+                if (hasInvisible) animateIn();
+            }
+        });
+
+        if (containerRef.value) {
+            observer.observe(containerRef.value, { childList: true, subtree: true });
+        }
+
+        onUnmounted(() => observer.disconnect());
+    });
+
+    onUnmounted(() => ctx?.revert());
+
+    return { animateIn, animateOut };
+}