visualfries 0.1.0

package/dist/animations/builders/WordHighlighterAnimationBuilder.d.ts

@@ -0,0 +1,15 @@
+import type { Animation } from '../..';
+import type { ComponentData } from '../..';
+import type { SplitTextCache } from '../SplitTextCache.js';
+export declare class WordHighlighterAnimationBuilder {
+    static build(data: ComponentData, target: HTMLElement, animationData: Record<string, any>, splitTextCache: SplitTextCache): Animation[];
+    private static createWordHighlightAnimations;
+    private static prepareHighlightStyles;
+    private static createHighlightAnimation;
+    private static createUnhighlightAnimation;
+    private static createBackgroundHighlightAnimation;
+    private static createBackgroundElement;
+    private static getBackgroundConfig;
+    private static initializeBackgroundElement;
+    private static buildBackgroundAnimation;
+}

package/dist/animations/builders/WordHighlighterAnimationBuilder.js

@@ -0,0 +1,180 @@
+import { get } from 'lodash-es';
+import { wordsHighlighter } from '../presets/words.js';
+import { AnimationPresetFactory } from './AnimationPresetFactory.js';
+import { ColorTransformer } from '../../transformers/ColorTransformer.js';
+export class WordHighlighterAnimationBuilder {
+    static build(data, target, animationData, splitTextCache) {
+        if (data.type !== 'TEXT') {
+            return [];
+        }
+        const activeWord = get(data, 'appearance.text.activeWord', null);
+        if (!activeWord?.enabled) {
+            return [];
+        }
+        const config = {
+            activeWord,
+            data,
+            animationData,
+            target,
+            splitTextCache
+        };
+        return this.createWordHighlightAnimations(config);
+    }
+    static createWordHighlightAnimations(config) {
+        const animations = [];
+        const styles = this.prepareHighlightStyles(config);
+        // Create main highlight animation
+        const highlightAnimation = this.createHighlightAnimation(config.data.id, styles.highlight, config.animationData);
+        animations.push(highlightAnimation);
+        // Create unhighlight animation if needed
+        const unhighlightAnimation = this.createUnhighlightAnimation(config.data.id, styles.original, config.animationData);
+        if (unhighlightAnimation) {
+            animations.push(unhighlightAnimation);
+        }
+        // Create background highlight animation if needed
+        const backgroundAnimation = this.createBackgroundHighlightAnimation(config);
+        if (backgroundAnimation) {
+            animations.push(backgroundAnimation);
+        }
+        return animations;
+    }
+    static prepareHighlightStyles(config) {
+        const { activeWord, data } = config;
+        const highlightStyles = ColorTransformer.transform(activeWord.color, 'text');
+        const originalStyles = ColorTransformer.transform(data.appearance.text?.color, 'text');
+        // Handle font weight if specified
+        if (get(activeWord, 'fontWeight', undefined)) {
+            highlightStyles.fontWeight = activeWord.fontWeight;
+            originalStyles.fontWeight = data.appearance.text?.fontWeight ?? 'normal';
+        }
+        return {
+            highlight: highlightStyles,
+            original: originalStyles
+        };
+    }
+    static createHighlightAnimation(componentId, styles, animationData) {
+        const animation = AnimationPresetFactory.from(wordsHighlighter)
+            .resetTimeline()
+            .timeline()
+            .target('words')
+            .to({
+            ...styles,
+            stagger: { type: 'fromData', dataKey: 'wordStartTimes' }
+        })
+            .build();
+        return {
+            id: `words-highlight-${componentId}`,
+            name: 'Words Highlight',
+            animation,
+            startAt: 0
+        };
+    }
+    static createUnhighlightAnimation(componentId, originalStyles, animationData) {
+        if (!animationData.wordUnhighlightTimes) {
+            return null;
+        }
+        const animation = AnimationPresetFactory.from(wordsHighlighter)
+            .resetTimeline()
+            .timeline()
+            .target('words')
+            .to({
+            ...originalStyles,
+            stagger: { type: 'fromData', dataKey: 'wordUnhighlightTimes' }
+        })
+            .build();
+        return {
+            id: `words-highlight-${componentId}-unhighlight`,
+            name: 'Words Unhighlight',
+            animation
+        };
+    }
+    static createBackgroundHighlightAnimation(config) {
+        const { activeWord, target, splitTextCache, data, animationData } = config;
+        if (!activeWord.backgroundColor) {
+            return null;
+        }
+        const words = splitTextCache.getSplitText(target, 'words');
+        if (!words?.length) {
+            return null;
+        }
+        const bgHighlighter = this.createBackgroundElement(target);
+        const backgroundConfig = this.getBackgroundConfig(activeWord);
+        const bgStyles = ColorTransformer.transform(activeWord.backgroundColor, 'background');
+        this.initializeBackgroundElement(bgHighlighter, words[0], backgroundConfig, bgStyles);
+        const animation = this.buildBackgroundAnimation(data.id, words, animationData, backgroundConfig, bgStyles);
+        return {
+            id: `words-background-highlight-${data.id}`,
+            name: 'Words Background Highlight',
+            animation,
+            startAt: 0
+        };
+    }
+    static createBackgroundElement(target) {
+        const bgHighlighter = document.createElement('div');
+        bgHighlighter.id = 'highlighter-bg';
+        bgHighlighter.style.position = 'absolute';
+        bgHighlighter.style.pointerEvents = 'none';
+        target.prepend(bgHighlighter);
+        return bgHighlighter;
+    }
+    static getBackgroundConfig(activeWord) {
+        return {
+            paddingX: get(activeWord, 'backgroundPaddingX', 25),
+            paddingY: get(activeWord, 'backgroundPaddingY', 10),
+            borderRadius: get(activeWord, 'backgroundBorderRadius', 10)
+        };
+    }
+    static initializeBackgroundElement(bgHighlighter, firstWord, config, bgStyles) {
+        const { paddingX, paddingY, borderRadius } = config;
+        bgHighlighter.style.left = `${firstWord.offsetLeft - paddingX}px`;
+        bgHighlighter.style.top = `${firstWord.offsetTop - paddingY}px`;
+        bgHighlighter.style.width = `${firstWord.clientWidth + 2 * paddingX}px`;
+        bgHighlighter.style.height = `${firstWord.clientHeight + 2 * paddingY}px`;
+        bgHighlighter.style.borderRadius = `${borderRadius}px`;
+        bgHighlighter.style.opacity = '1';
+        if (bgStyles) {
+            Object.entries(bgStyles).forEach(([key, value]) => {
+                // Check if key is a valid writable style property
+                if (key in bgHighlighter.style) {
+                    bgHighlighter.style[key] = String(value);
+                }
+                else {
+                    // For custom properties or CSS variables, use setProperty
+                    bgHighlighter.style.setProperty(key, String(value));
+                }
+            });
+        }
+    }
+    static buildBackgroundAnimation(componentId, words, animationData, backgroundConfig, bgStyles) {
+        const presetComposer = AnimationPresetFactory.create(`words-bg-highlight-anim-${componentId}`);
+        const timelineComposer = presetComposer.timeline();
+        const targetComposer = timelineComposer.target('#highlighter-bg');
+        const wordStartTimes = animationData.wordStartTimes ?? [];
+        if (wordStartTimes.length <= 1) {
+            return timelineComposer.build();
+        }
+        const { paddingX, paddingY, borderRadius } = backgroundConfig;
+        for (let i = 0; i < wordStartTimes.length; i++) {
+            const currentWord = words[i];
+            if (!currentWord) {
+                console.warn(`WordHighlighter: Word element at index ${i} is missing.`);
+                continue;
+            }
+            const startTime = parseFloat(wordStartTimes[i].toFixed(3));
+            targetComposer
+                .to({
+                borderRadius: `${borderRadius}px`,
+                left: currentWord.offsetLeft - paddingX,
+                top: currentWord.offsetTop - paddingY,
+                width: currentWord.clientWidth + 2 * paddingX,
+                height: currentWord.clientHeight + 2 * paddingY,
+                duration: 0.15,
+                ease: 'power1.out',
+                // delay: startTime,
+                ...bgStyles
+            }, startTime)
+                .position(0);
+        }
+        return timelineComposer.build();
+    }
+}

package/dist/animations/engines/AnimationEngineAdaptor.d.ts

@@ -0,0 +1,107 @@
+import type { AnimationContext } from '../AnimationContext.js';
+export type EngineTarget = any;
+export type EngineTimeline = any;
+export type EngineStaggerOptions = any;
+export interface AnimationEngineAdaptor {
+    /**
+     * Creates a new timeline instance from the animation engine.
+     * @param options - Engine-specific timeline options.
+     * @returns An instance of the engine's timeline.
+     */
+    createTimeline(options?: Record<string, any>): EngineTimeline;
+    /**
+     * Adds a tween to the given timeline.
+     * @param timeline - The engine timeline instance to add the tween to.
+     * @param targets - The target(s) for the animation.
+     * @param method - The animation method ('to', 'from', 'fromTo', 'set').
+     * @param vars - An object containing properties to animate and animation parameters (duration, ease, etc.).
+     *                 This should include resolved values (e.g., data references already looked up).
+     *                 For 'fromTo', 'vars.from' will contain the from-properties.
+     * @param position - The position in the timeline where the tween should be inserted (e.g., absolute time, label, relative offset).
+     */
+    addTween(timeline: EngineTimeline, targets: EngineTarget | EngineTarget[], method: 'to' | 'from' | 'fromTo' | 'set', vars: Record<string, any>, position?: string | number): number;
+    /**
+     * Resolves stagger options, especially 'fromData' type, into engine-specific stagger configuration.
+     * @param staggerDefinition - The stagger object from the JSON preset.
+     * @param context - The animation context, for accessing data like `wordTimestamps`.
+     * @param tweenDuration - The duration of the individual tween that stagger is applied to (can be undefined).
+     * @returns Engine-specific stagger options or a value that the engine understands for staggering.
+     */
+    resolveStagger(staggerDefinition: Record<string, any> | number, context: AnimationContext, tweenDuration?: number): EngineStaggerOptions;
+    /**
+     * Plays the given timeline.
+     * @param timeline - The engine timeline instance to play.
+     * @param position - (Optional) Time or label from which to start playing.
+     */
+    play(timeline: EngineTimeline, position?: string | number): void;
+    /**
+     * Pauses the given timeline.
+     * @param timeline - The engine timeline instance to pause.
+     */
+    pause(timeline: EngineTimeline): void;
+    /**
+     * Resumes the given timeline.
+     * @param timeline - The engine timeline instance to resume.
+     * @param position - (Optional) Time or label from which to resume playing.
+     */
+    resume(timeline: EngineTimeline, position?: string | number): void;
+    /**
+     * Seeks to a specific time or label in the timeline.
+     * @param timeline - The engine timeline instance.
+     * @param position - Time (seconds) or label to seek to.
+     * @param suppressEvents - (Optional) If true, suppress events during the seek (engine dependent).
+     */
+    seek(timeline: EngineTimeline, position: string | number, suppressEvents?: boolean): void;
+    /**
+     * Gets the total duration of a timeline.
+     * @param timeline - The engine timeline instance.
+     * @returns The duration in seconds.
+     */
+    totalDuration(timeline: EngineTimeline): number;
+    /**
+     * Kills/destroys the timeline and its animations, removing them from the engine.
+     * @param timeline - The engine timeline instance to kill.
+     */
+    kill(timeline: EngineTimeline): void;
+    /**
+     * (Optional) Utility to convert a generic property value (which might be a data reference)
+     * into its actual value. This might be handled by the AnimationBuilder before calling addTween,
+     * or the adaptor can provide a utility if the engine has specific ways to handle dynamic values.
+     * For now, let's assume AnimationBuilder resolves data references.
+     */
+    /**
+     * (Optional) Helper to create a "pause" or empty tween in the timeline.
+     * @param timeline The engine timeline to add the pause to.
+     * @param duration The duration of the pause.
+     * @param position The position in the timeline.
+     */
+    addPause(timeline: EngineTimeline, duration: number, position?: string | number): void;
+    /**
+     * (Optional) Adds a label to the timeline at the current end or a specific time.
+     * @param timeline The engine timeline.
+     * @param label The name of the label.
+     * @param position The position for the label.
+     */
+    addLabel(timeline: EngineTimeline, label: string, position?: string | number): void;
+    /**
+     * (Optional) Adds a callback to the timeline.
+     * @param timeline The engine timeline.
+     * @param callback The function to call.
+     * @param position The position for the callback.
+     */
+    addCallback(timeline: EngineTimeline, callback: () => void, position?: string | number): void;
+    /**
+     * (Optional) Adds a callback to the timeline.
+     * @param timeline The engine timeline.
+     * @param callback The function to call.
+     */
+    onComplete(timeline: EngineTimeline, callback: () => void): void;
+    /**
+     * Repositions a label by removing it and adding it again at a new position.
+     * This should cause any animations positioned at that label to move to the new position.
+     * @param timeline The engine timeline.
+     * @param labelName The name of the label to reposition.
+     * @param newPosition The new position for the label.
+     */
+    repositionLabel(timeline: EngineTimeline, labelName: string, newPosition: string | number): void;
+}

package/dist/animations/engines/AnimationEngineAdaptor.js

@@ -0,0 +1 @@
+export {};

package/dist/animations/engines/GSAPEngineAdaptor.d.ts

@@ -0,0 +1,21 @@
+import type { AnimationEngineAdaptor, EngineTarget, EngineStaggerOptions } from './AnimationEngineAdaptor.ts';
+import type { AnimationContext } from '../AnimationContext.ts';
+type GsapEngineTimeline = gsap.core.Timeline;
+export declare class GsapEngineAdaptor implements AnimationEngineAdaptor {
+    createTimeline(options?: gsap.TimelineVars): GsapEngineTimeline;
+    addTween(timeline: GsapEngineTimeline, targets: EngineTarget | EngineTarget[], method: 'to' | 'from' | 'fromTo' | 'set', vars: gsap.TweenVars, // GSAP's TweenVars is very flexible
+    position?: string | number): number;
+    resolveStagger(staggerDefinition: Record<string, any> | number, context: AnimationContext, _tweenDuration?: number): EngineStaggerOptions;
+    play(timeline: GsapEngineTimeline, position?: string | number): void;
+    pause(timeline: GsapEngineTimeline): void;
+    resume(timeline: GsapEngineTimeline, position?: string | number): void;
+    seek(timeline: GsapEngineTimeline, position: string | number, suppressEvents?: boolean): void;
+    totalDuration(timeline: GsapEngineTimeline): number;
+    kill(timeline: GsapEngineTimeline): void;
+    addPause(timeline: GsapEngineTimeline, duration: number, position?: string | number): void;
+    addLabel(timeline: GsapEngineTimeline, label: string, position?: string | number): void;
+    addCallback(timeline: GsapEngineTimeline, callback: () => void, position?: string | number): void;
+    onComplete(timeline: GsapEngineTimeline, callback: () => void): void;
+    repositionLabel(timeline: GsapEngineTimeline, labelName: string, newPosition: string | number): void;
+}
+export {};

package/dist/animations/engines/GSAPEngineAdaptor.js

@@ -0,0 +1,145 @@
+import { gsap } from 'gsap';
+import { get } from 'lodash-es';
+export class GsapEngineAdaptor {
+    createTimeline(options) {
+        if (!options) {
+            options = {};
+        }
+        const revertAfterComplete = get(options, 'revertAfterComplete', false);
+        // options.smoothChildTiming = true;
+        if (revertAfterComplete) {
+            options.onComplete = function () {
+                this.seek(0);
+            };
+        }
+        const tl = gsap.timeline(options); // options
+        tl.callbackScope = tl;
+        return tl;
+    }
+    addTween(timeline, targets, method, vars, // GSAP's TweenVars is very flexible
+    position) {
+        if (!targets || (Array.isArray(targets) && targets.length === 0)) {
+            console.warn('GSAP addTween: No targets provided.');
+            return 0;
+        }
+        let populatedVars = { ...vars }; // Clone vars to avoid mutating original from preset
+        // GSAP's .fromTo() expects 'from' vars as the second argument,
+        // and 'to' vars as the third.
+        // Our 'vars' for 'fromTo' contains 'vars.from' and the 'to' vars directly in 'vars'.
+        if (method === 'fromTo') {
+            const fromVars = populatedVars.from || {};
+            delete populatedVars.from; // Remove it from the 'to' vars object
+            timeline.set(targets, fromVars, position);
+            const tween = timeline.to(targets, populatedVars, position);
+            return tween.duration();
+        }
+        const tween = timeline[method](targets, populatedVars, position);
+        return tween.duration();
+    }
+    resolveStagger(staggerDefinition, context, _tweenDuration // GSAP often handles duration within stagger context if 'amount' is used
+    ) {
+        // Returns GSAPStaggerVars
+        if (typeof staggerDefinition === 'number') {
+            return staggerDefinition; // GSAP shorthand for { each: number }
+        }
+        const { type, dataKey, ...restOfStagger } = staggerDefinition;
+        if (type === 'fromData' && dataKey) {
+            const timingsArray = context.getData(dataKey);
+            if (!Array.isArray(timingsArray)) {
+                console.warn(`Stagger 'fromData': dataKey "${dataKey}" did not resolve to an array.`);
+                return restOfStagger; // Fallback to other stagger props if any
+            }
+            // GSAP functional stagger:
+            // The function receives (index, target, targetsArray)
+            // We want the Nth word to start at timingsArray[N] relative to this stagger block's start.
+            return (index, _target, _targets) => {
+                // Ensure the specific timing applies to the start of the individual tween.
+                // If the stagger block itself has an overall duration ('amount'), GSAP handles distribution.
+                // If 'each' is explicitly needed for individual tween starts based on data,
+                // this functional value for 'each' is very powerful.
+                // However, GSAP's 'amount' along with a from/distribution model often handles this.
+                // For precise start times from an array, a function directly controlling delay is more robust.
+                //
+                // Simpler approach if timingsArray are ABSOLUTE start times for items within this stagger block:
+                // We return a value that GSAP interprets as the delay for *that specific element*.
+                // GSAP's stagger `each` can accept a function.
+                // But for explicit timings, it's usually better to create individual tweens
+                // or use a function that returns the DELAY.
+                //
+                // Let's assume timingsArray contains offsets for each element for this stagger.
+                // This is a bit tricky as GSAP's `each` or `amount` with a function is nuanced.
+                // A common GSAP pattern for fully custom time placement within a stagger:
+                // The function for 'each' might determine *how much longer* than the PREVIOUS one,
+                // or 'amount' is used to distribute over a total time.
+                //
+                // If `timingsArray` are desired *absolute start times* within the current tween:
+                // The most robust way in GSAP, if not using `amount`, is for the function
+                // passed to `stagger` to directly return the *delay from the start of the stagger sequence*.
+                // This is often what a functional value for `each` or if `stagger` itself is a function would achieve.
+                // For now, let's assume `timingsArray[index]` is the desired start offset for `targets[index]`.
+                // This might need refinement based on how GSAP's `stagger` function is structured.
+                // A direct mapping to individual delays is typically done by passing a function to stagger itself:
+                // stagger: (index, target, list) => timingsArray[index] // This is the delay for that element
+                if (timingsArray && index < timingsArray.length) {
+                    return timingsArray[index];
+                }
+                return 0; // Default delay if no timing found
+            };
+        }
+        return staggerDefinition; // Standard GSAP stagger object or number
+    }
+    play(timeline, position) {
+        timeline.play(position);
+    }
+    pause(timeline) {
+        timeline.pause();
+    }
+    resume(timeline, position) {
+        // GSAP's play() handles resuming correctly. If a position is given, it seeks and plays.
+        timeline.play(position);
+    }
+    seek(timeline, position, suppressEvents = true) {
+        timeline.seek(position, suppressEvents);
+    }
+    totalDuration(timeline) {
+        return timeline.totalDuration();
+    }
+    kill(timeline) {
+        timeline.kill();
+    }
+    addPause(timeline, duration, position) {
+        // GSAP timeline.addPause(position, callback, params)
+        // To add a pause of a certain duration, we can add an empty tween or a specific delay.
+        // A common way is to add a label then another label offset by duration,
+        // or simply an empty tween if that's how you want to signify it.
+        // Or more directly:
+        if (position !== undefined) {
+            timeline.addLabel('pauseStart', position);
+            timeline.addLabel('pauseEnd', `+= ${duration}`);
+        }
+        else {
+            timeline.addPause(`+=${duration}`); // Adds a pause at the current end for 'duration' seconds.
+            // Actually, GSAP's addPause creates a hard stop.
+            // To create a gap of 'duration':
+            timeline.to({}, { duration }, position); // Empty tween to create a gap
+        }
+    }
+    addLabel(timeline, label, position) {
+        timeline.addLabel(label, position);
+    }
+    addCallback(timeline, callback, position) {
+        timeline.call(callback, undefined, position); // GSAP's call method
+    }
+    onComplete(timeline, callback) {
+        timeline.onComplete(callback);
+    }
+    repositionLabel(timeline, labelName, newPosition) {
+        if (!get(timeline, 'labels.' + labelName)) {
+            console.warn(`Label "${labelName}" not found in timeline`);
+        }
+        else {
+            timeline.removeLabel(labelName);
+        }
+        timeline.addLabel(labelName, newPosition);
+    }
+}

package/dist/animations/presets/index.d.ts

@@ -0,0 +1,2 @@
+export * from './words.js';
+export * from './lines.js';

package/dist/animations/presets/index.js

@@ -0,0 +1,3 @@
+export * from './words.js';
+// Line-based animations
+export * from './lines.js';

package/dist/animations/presets/lines.d.ts

@@ -0,0 +1,52 @@
+import type { AnimationPreset } from '../..';
+export declare const linesHighlighter: AnimationPreset;
+/**
+ * Lines reveal and fade preset
+ * Reveals lines one by one with a scale effect
+ */
+export declare const linesRevealAndFade: AnimationPreset;
+/**
+ * Lines elastic preset
+ * Reveals lines with an elastic bounce effect
+ */
+export declare const linesElastic: AnimationPreset;
+/**
+ * Lines swipe left preset
+ * Lines slide in from right and out to left
+ */
+export declare const linesSwipeLeft: AnimationPreset;
+/**
+ * Lines exchange preset
+ * Lines scale in and out with a smooth transition
+ */
+export declare const linesExchange: AnimationPreset;
+/**
+ * Lines rolling preset
+ * Lines roll in with 3D rotation effect
+ */
+export declare const linesRolling: AnimationPreset;
+/**
+ * Lines spiral preset
+ * Lines spiral in with 3D rotation effect
+ */
+export declare const linesDna: AnimationPreset;
+/**
+ * Lines bounce preset
+ * Lines bounce in from the top
+ */
+export declare const linesBounce: AnimationPreset;
+/**
+ * Lines glitch preset
+ * Lines appear with glitchy rough animation
+ */
+export declare const linesJiggle: AnimationPreset;
+/**
+ * Lines rotate preset
+ * Lines rotate in with scale effect
+ */
+export declare const rotatingWarpText: AnimationPreset;
+/**
+ * Lines lift up preset
+ * Lines lift up with alternating rotation
+ */
+export declare const coolLinesAnimation: AnimationPreset;