move.gl 0.0.1 → 0.0.2

package/src/scss/mixins/animations/_base.scss

@@ -0,0 +1,403 @@
+////
+///
+/// Base Animations Mixin Module
+/// =========================================================================
+///
+/// Provides the foundational animation infrastructure for move.gl,
+/// including the base animation mixin used by all other animation modules,
+/// accessibility considerations for reduced motion preferences, and
+/// utility mixins for common animation patterns.
+///
+/// @group Animations
+/// @author Scape Agency
+/// @link https://move.gl
+/// @since 0.1.0 initial release
+/// @access public
+///
+////
+
+
+// ============================================================================
+// Use
+// ============================================================================
+
+@use "sass:map";
+@use "sass:list";
+@use "../../dev" as *;
+@use "../../variables" as *;
+
+
+// ============================================================================
+// Base Animation Mixin
+// ============================================================================
+
+///
+/// Base Animation Mixin
+/// -----------------------------------------------------------------------
+/// The foundation mixin for all animations. Provides a consistent
+/// structure for defining animations with customizable properties.
+///
+/// @name animate_base
+/// @param {String} $name [none] - The animation name (keyframes reference)
+/// @param {Time} $duration [$animate_base_duration] - Animation duration
+/// @param {String} $timing_function [$animate_base_timing_function] - Easing
+/// @param {Number|String} $iteration_count - Number of iterations
+/// @param {Time} $delay [$animate_base_delay] - Delay before start
+/// @param {String} $direction [$animate_base_direction] - Direction
+/// @param {String} $fill_mode [both] - Styles before/after animation
+/// @param {String} $play_state [running] - Running or paused
+///
+/// @example scss - Basic usage
+///   .element {
+///     @include animate_base(fadeIn, 0.5s, ease-out, 1);
+///   }
+///
+@mixin animate_base(
+    $name: none,
+    $duration: $animate_base_duration,
+    $timing_function: $animate_base_timing_function,
+    $iteration_count: $animate_base_iteration_count,
+    $delay: $animate_base_delay,
+    $direction: $animate_base_direction,
+    $fill_mode: both,
+    $play_state: running
+) {
+    animation-name: $name;
+    animation-duration: $duration;
+    animation-timing-function: $timing_function;
+    animation-iteration-count: $iteration_count;
+    animation-delay: $delay;
+    animation-direction: $direction;
+    animation-fill-mode: $fill_mode;
+    animation-play-state: $play_state;
+}
+
+
+///
+/// Animation Shorthand Mixin
+/// -----------------------------------------------------------------------
+/// Applies animation using the shorthand property for concise output.
+///
+/// @name animate_shorthand
+/// @param {String} $name - Animation name
+/// @param {Time} $duration [0.5s] - Duration
+/// @param {String} $timing [ease-in-out] - Timing function
+/// @param {Time} $delay [0s] - Delay
+/// @param {Number|String} $iterations [1] - Iteration count
+/// @param {String} $direction [normal] - Direction
+/// @param {String} $fill_mode [both] - Fill mode
+///
+@mixin animate_shorthand(
+    $name,
+    $duration: 0.5s,
+    $timing: ease-in-out,
+    $delay: 0s,
+    $iterations: 1,
+    $direction: normal,
+    $fill_mode: both
+) {
+    animation: $name $duration $timing $delay $iterations $direction $fill_mode;
+}
+
+
+// ============================================================================
+// Animation State Mixins
+// ============================================================================
+
+///
+/// Paused Animation State
+/// -----------------------------------------------------------------------
+/// Pauses an animation. Useful for hover effects or JavaScript control.
+///
+@mixin animate_paused {
+    animation-play-state: paused;
+}
+
+///
+/// Running Animation State
+/// -----------------------------------------------------------------------
+/// Ensures an animation is running.
+///
+@mixin animate_running {
+    animation-play-state: running;
+}
+
+
+// ============================================================================
+// Animation Property Mixins
+// ============================================================================
+
+///
+/// Animation Duration
+/// -----------------------------------------------------------------------
+/// Sets the animation duration independently.
+///
+/// @param {Time} $duration - The duration value
+///
+@mixin animate_duration($duration) {
+    animation-duration: $duration;
+}
+
+///
+/// Animation Delay
+/// -----------------------------------------------------------------------
+/// Sets the animation delay independently.
+///
+/// @param {Time} $delay - The delay value
+///
+@mixin animate_delay($delay) {
+    animation-delay: $delay;
+}
+
+///
+/// Animation Timing Function
+/// -----------------------------------------------------------------------
+/// Sets the animation timing function independently.
+///
+/// @param {String} $timing - The timing function
+///
+@mixin animate_timing($timing) {
+    animation-timing-function: $timing;
+}
+
+///
+/// Animation Iteration Count
+/// -----------------------------------------------------------------------
+/// Sets the animation iteration count independently.
+///
+/// @param {Number|String} $count - Number of iterations or 'infinite'
+///
+@mixin animate_iterations($count) {
+    animation-iteration-count: $count;
+}
+
+
+// ============================================================================
+// Animation Fill Mode Mixins
+// ============================================================================
+
+///
+/// Fill Mode - Forwards
+/// -----------------------------------------------------------------------
+/// Retains styles from the last keyframe after animation ends.
+///
+@mixin animate_fill_forwards {
+    animation-fill-mode: forwards;
+}
+
+///
+/// Fill Mode - Backwards
+/// -----------------------------------------------------------------------
+/// Applies styles from the first keyframe before animation starts.
+///
+@mixin animate_fill_backwards {
+    animation-fill-mode: backwards;
+}
+
+///
+/// Fill Mode - Both
+/// -----------------------------------------------------------------------
+/// Combines forwards and backwards fill modes.
+///
+@mixin animate_fill_both {
+    animation-fill-mode: both;
+}
+
+///
+/// Fill Mode - None
+/// -----------------------------------------------------------------------
+/// No fill mode applied.
+///
+@mixin animate_fill_none {
+    animation-fill-mode: none;
+}
+
+
+// ============================================================================
+// Animation Direction Mixins
+// ============================================================================
+
+///
+/// Direction - Alternate
+/// -----------------------------------------------------------------------
+/// Animation alternates direction on each iteration.
+///
+@mixin animate_alternate {
+    animation-direction: alternate;
+}
+
+///
+/// Direction - Reverse
+/// -----------------------------------------------------------------------
+/// Animation plays in reverse.
+///
+@mixin animate_reverse {
+    animation-direction: reverse;
+}
+
+///
+/// Direction - Alternate Reverse
+/// -----------------------------------------------------------------------
+/// Animation alternates, starting in reverse.
+///
+@mixin animate_alternate_reverse {
+    animation-direction: alternate-reverse;
+}
+
+
+// ============================================================================
+// Keyframe Generator Mixin
+// ============================================================================
+
+///
+/// Dynamic Keyframe Generator
+/// -----------------------------------------------------------------------
+/// Generates keyframe animations from a map of percentages and properties.
+///
+/// @name keyframe_animation
+/// @param {String} $name - The animation name
+/// @param {Map} $keyframes - Map of keyframes (percentage: properties)
+///
+/// @example scss - Usage
+///   @include keyframe_animation('slide-in', (
+///     0%: (transform: translateX(-100%), opacity: 0),
+///     100%: (transform: translateX(0), opacity: 1)
+///   ));
+///
+@mixin keyframe_animation($name, $keyframes) {
+    @keyframes #{$name} {
+        @each $percentage, $properties in $keyframes {
+            #{$percentage} {
+                @each $property, $value in $properties {
+                    #{$property}: #{$value};
+                }
+            }
+        }
+    }
+}
+
+
+// ============================================================================
+// Performance Optimization
+// ============================================================================
+
+///
+/// Hardware Acceleration
+/// -----------------------------------------------------------------------
+/// Enables hardware acceleration for smoother animations.
+/// Use sparingly as it can increase memory usage.
+///
+@mixin animate_gpu {
+    transform: translateZ(0);
+    backface-visibility: hidden;
+    perspective: 1000px;
+}
+
+///
+/// Will Change Hint
+/// -----------------------------------------------------------------------
+/// Hints to the browser which properties will animate.
+/// Remove after animation completes to free resources.
+///
+/// @param {String...} $properties - Properties that will change
+///
+@mixin animate_will_change($properties...) {
+    will-change: $properties;
+}
+
+
+// ============================================================================
+// Accessibility - Reduced Motion
+// ============================================================================
+
+///
+/// Reduced Motion Media Query
+/// -----------------------------------------------------------------------
+/// Wraps content in a prefers-reduced-motion media query.
+/// Use to provide alternative non-animated styles.
+///
+/// @content Styles to apply when reduced motion is preferred
+///
+@mixin prefers_reduced_motion {
+    @media (prefers-reduced-motion: reduce) {
+        @content;
+    }
+}
+
+///
+/// Respects Reduced Motion
+/// -----------------------------------------------------------------------
+/// Applies animation only when user hasn't requested reduced motion.
+///
+/// @content Animation styles
+///
+@mixin respects_motion {
+    @media (prefers-reduced-motion: no-preference) {
+        @content;
+    }
+}
+
+///
+/// Global Reduced Motion Reset
+/// -----------------------------------------------------------------------
+/// Disables all animations and transitions for users who prefer
+/// reduced motion. Apply at root level for comprehensive accessibility.
+///
+@mixin reduced_motion_global {
+    @media (prefers-reduced-motion: reduce) {
+        *,
+        *::before,
+        *::after {
+            animation-duration: 0.01ms !important;
+            animation-iteration-count: 1 !important;
+            transition-duration: 0.01ms !important;
+            scroll-behavior: auto !important;
+        }
+    }
+}
+
+
+// ============================================================================
+// Animation Composition
+// ============================================================================
+
+///
+/// Staggered Animation Delay
+/// -----------------------------------------------------------------------
+/// Creates staggered animation delays for child elements.
+///
+/// @param {Number} $count - Number of children to stagger
+/// @param {Time} $base_delay [0.1s] - Base delay increment
+/// @param {Time} $initial_delay [0s] - Initial delay for first child
+///
+/// @example scss - Usage
+///   .list {
+///     @include animate_stagger(5, 0.1s);
+///   }
+///
+@mixin animate_stagger($count, $base_delay: 0.1s, $initial_delay: 0s) {
+    @for $i from 1 through $count {
+        &:nth-child(#{$i}) {
+            animation-delay: $initial_delay + ($base_delay * ($i - 1));
+        }
+    }
+}
+
+///
+/// Multiple Animations
+/// -----------------------------------------------------------------------
+/// Applies multiple animations to a single element.
+///
+/// @param {List} $animations... - Animation shorthand values
+///
+/// @example scss - Usage
+///   .element {
+///     @include animate_multiple(
+///       fadeIn 0.5s ease-out,
+///       slideUp 0.5s ease-out 0.2s
+///     );
+///   }
+///
+@mixin animate_multiple($animations...) {
+    animation: $animations;
+}

package/src/scss/mixins/animations/_beat.scss

@@ -0,0 +1,137 @@
+////
+///
+/// Beat Animations Mixin Module
+/// ===========================================================================
+///
+/// Provides SCSS mixins for creating rhythmic beat animations that scale
+/// elements up and down in pulsating patterns. Includes basic beat, beat
+/// with fade effect, and double beat (heartbeat-like) variations.
+///
+/// @group Animations
+/// @author Scape Agency
+/// @link https://move.gl
+/// @since 0.1.0 initial release
+/// @access public
+///
+////
+
+
+// ============================================================================
+// Use
+// ============================================================================
+
+@use "../../dev" as *;
+@use "../../variables" as *;
+@use "../keyframes" as *;
+@use "base" as *;
+
+
+// ============================================================================
+// Mixins
+// ============================================================================
+
+///
+/// Beat Animation
+/// ---------------------------------------------------------------------------
+/// Creates a beat animation that scales an element up and down rhythmically.
+///
+/// @name animate_beat
+/// @param {Number} $scale [$animate_scale_beat] - The scale factor for the beat animation
+/// @param {Time} $duration [$animate_base_duration] - The duration of the animation
+/// @param {String} $timing_function [$animate_base_timing_function] - The timing function
+/// @param {Number|String} $iteration_count [$animate_base_iteration_count] - Number of iterations
+///
+/// @example scss - Basic usage
+///   .element {
+///     @include animate_beat;
+///   }
+///
+/// @example scss - Custom scale and duration
+///   .element {
+///     @include animate_beat(1.3, 0.8s);
+///   }
+///
+@mixin animate_beat(
+    $scale: $animate_scale_beat,
+    $duration: $animate_base_duration,
+    $timing_function: $animate_base_timing_function,
+    $iteration_count: $animate_base_iteration_count
+) {
+    @include animate_base(
+        animate_beat,
+        $duration,
+        $timing_function,
+        $iteration_count
+    );
+    @include keyframes_animate_beat($scale);
+}
+
+
+///
+/// Beat Fade Animation
+/// ---------------------------------------------------------------------------
+/// Combines a beat animation with a fade effect, scaling the element while
+/// simultaneously changing its opacity for a more subtle pulsating effect.
+///
+/// @name animate_beat_fade
+/// @param {Number} $opacity [$animate_opacity_fade] - Opacity level at animation midpoint
+/// @param {Number} $scale [$animate_scale_beat_fade] - The scale factor for the beat
+/// @param {Time} $duration [$animate_base_duration] - The duration of the animation
+/// @param {String} $timing_function [$animate_base_timing_function_fade] - The timing function
+/// @param {Number|String} $iteration_count [$animate_base_iteration_count] - Number of iterations
+///
+/// @example scss - Usage
+///   .element {
+///     @include animate_beat_fade;
+///   }
+///
+@mixin animate_beat_fade(
+    $opacity: $animate_opacity_fade,
+    $scale: $animate_scale_beat_fade,
+    $duration: $animate_base_duration,
+    $timing_function: $animate_base_timing_function_fade,
+    $iteration_count: $animate_base_iteration_count
+) {
+    @include animate_base(
+        animate_beat_fade,
+        $duration,
+        $timing_function,
+        $iteration_count
+    );
+    @include keyframes_animate_beat_fade($opacity, $scale);
+}
+
+
+///
+/// Double Beat Animation
+/// ---------------------------------------------------------------------------
+/// Creates a double beat animation simulating a heartbeat or pulsating effect.
+/// The element scales down, then up larger, then down again.
+///
+/// @name animate_beat_double
+/// @param {Number} $scale_small [$animate_scale_beat_double_small] - Smaller scale factor
+/// @param {Number} $scale_large [$animate_scale_beat_double_large] - Larger scale factor
+/// @param {Time} $duration [$animate_base_duration] - The duration of the animation
+/// @param {String} $timing_function [$animate_base_timing_function] - The timing function
+/// @param {Number|String} $iteration_count [$animate_base_iteration_count] - Number of iterations
+///
+/// @example scss - Usage
+///   .heartbeat-icon {
+///     @include animate_beat_double;
+///   }
+///
+@mixin animate_beat_double(
+    $scale_small: $animate_scale_beat_double_small,
+    $scale_large: $animate_scale_beat_double_large,
+    $duration: $animate_base_duration,
+    $timing_function: $animate_base_timing_function,
+    $iteration_count: $animate_base_iteration_count
+) {
+    @include animate_base(
+        animate_beat_double,
+        $duration,
+        $timing_function,
+        $iteration_count
+    );
+    @include keyframes_animate_beat_double($scale_small, $scale_large);
+}

package/src/scss/mixins/animations/_blink.scss

@@ -0,0 +1,159 @@
+////
+///
+/// Blink Animations Mixin Module
+/// ===========================================================================
+///
+/// Provides blinking animations for cursor effects, status indicators, and
+/// attention elements. Includes rapid, slow, and fade variants with
+/// customizable opacity levels and timing functions.
+///
+/// @group Animations
+/// @author Scape Agency
+/// @link https://move.gl
+/// @since 0.1.0 initial release
+/// @access public
+///
+////
+
+
+// ============================================================================
+// Use
+// ============================================================================
+
+@use "../../dev" as *;
+@use "../../variables" as *;
+@use "../keyframes" as *;
+@use "base" as *;
+
+
+// ============================================================================
+// Mixins
+// ============================================================================
+
+
+///
+/// Blink Animation
+/// ---------------------------------------------------------------------------
+/// Creates a blink animation where the element alternates between visible
+/// and invisible states.
+///
+/// @name animate_blink
+/// @param {Time} $duration [$animate_base_duration] - Animation duration
+/// @param {String} $timing_function [step-end] - Timing function
+/// @param {Number|String} $iteration_count - Number of iterations
+/// @param {Number} $start_opacity [1] - Opacity at start and end
+/// @param {Number} $blink_opacity [0] - Opacity during blink
+///
+/// @example scss - Basic usage
+///   .cursor {
+///     @include animate_blink;
+///   }
+///
+@mixin animate_blink(
+    $duration: $animate_base_duration,
+    $timing_function: step-end,
+    $iteration_count: $animate_base_iteration_count,
+    $start_opacity: 1,
+    $blink_opacity: 0
+) {
+    @include animate_base(
+        animate_blink,
+        $duration,
+        $timing_function,
+        $iteration_count
+    );
+    @include keyframes_animate_blink($start_opacity, $blink_opacity);
+}
+
+
+///
+/// Rapid Blink Animation
+/// ---------------------------------------------------------------------------
+/// Creates a rapid blink animation where the element blinks quickly between
+/// visible and invisible states.
+///
+/// @name animate_blink_rapid
+/// @param {Time} $duration [$animate_base_duration_fast] - Animation duration
+/// @param {String} $timing_function [steps(2, end)] - Timing function
+/// @param {Number|String} $iteration_count - Number of iterations
+///
+/// @example scss - Usage
+///   .alert {
+///     @include animate_blink_rapid;
+///   }
+///
+@mixin animate_blink_rapid(
+    $duration: $animate_base_duration_fast,
+    $timing_function: steps(2, end),
+    $iteration_count: $animate_base_iteration_count
+) {
+    @include animate_base(
+        animate_blink_rapid,
+        $duration,
+        $timing_function,
+        $iteration_count
+    );
+    @include keyframes_animate_blink_rapid();
+}
+
+
+///
+/// Soft Blink Animation
+/// ---------------------------------------------------------------------------
+/// Creates a soft blink animation with a smooth transition in and out of
+/// visibility.
+///
+/// @name animate_blink_soft
+/// @param {Time} $duration [$animate_base_duration_slow] - Animation duration
+/// @param {String} $timing_function [ease-in-out] - Timing function
+/// @param {Number|String} $iteration_count - Number of iterations
+///
+/// @example scss - Usage
+///   .status {
+///     @include animate_blink_soft;
+///   }
+///
+@mixin animate_blink_soft(
+    $duration: $animate_base_duration_slow,
+    $timing_function: ease-in-out,
+    $iteration_count: $animate_base_iteration_count
+) {
+    @include animate_base(
+        animate_blink_soft,
+        $duration,
+        $timing_function,
+        $iteration_count
+    );
+    @include keyframes_animate_blink_soft();
+}
+
+
+///
+/// Alternating Blink Animation
+/// ---------------------------------------------------------------------------
+/// Creates an alternating blink animation where the element blinks at
+/// regular intervals.
+///
+/// @name animate_blink_alternate
+/// @param {Time} $duration [$animate_base_duration] - Animation duration
+/// @param {String} $timing_function [linear] - Timing function
+/// @param {Number|String} $iteration_count - Number of iterations
+///
+/// @example scss - Usage
+///   .indicator {
+///     @include animate_blink_alternate;
+///   }
+///
+@mixin animate_blink_alternate(
+    $duration: $animate_base_duration,
+    $timing_function: linear,
+    $iteration_count: $animate_base_iteration_count
+) {
+    @include animate_base(
+        animate_blink_alternate,
+        $duration,
+        $timing_function,
+        $iteration_count
+    );
+    @include keyframes_animate_blink_alternate();
+}