Class: Plushie::Animation::Spring

Inherits:
Data
  • Object
show all
Defined in:
lib/plushie/animation/spring.rb

Overview

Renderer-side physics-based spring descriptor.

Springs animate using a damped harmonic oscillator simulation. Unlike timed transitions, springs have no fixed duration: they settle naturally based on stiffness, damping, and mass. This makes them ideal for interactive animations where the target changes frequently (drag, scroll, hover) because interruption preserves velocity for smooth redirection.

== Presets

  • +:gentle+: slow, smooth, no overshoot
  • +:snappy+: quick, minimal overshoot
  • +:bouncy+: quick with visible overshoot
  • +:stiff+: very quick, crisp stop
  • +:molasses+: slow, heavy, deliberate

Examples:

Custom parameters

container("card",
  scale: Spring.build(to: 1.05, stiffness: 200, damping: 20))

Named preset

container("card",
  scale: Spring.build(to: 1.05, preset: :bouncy))

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(to:, from: nil, stiffness: 170, damping: 26, mass: 1.0, velocity: 0.0, on_complete: nil) ⇒ Spring

Returns a new instance of Spring.

Parameters:

  • to (Object) —

    target value (required)

  • from (Object, nil) (defaults to: nil) —

    starting value (nil = current value)

  • stiffness (Numeric) (defaults to: 170) —

    spring stiffness (default: 170)

  • damping (Numeric) (defaults to: 26) —

    damping ratio (default: 26)

  • mass (Numeric) (defaults to: 1.0) —

    oscillator mass (default: 1.0)

  • velocity (Numeric) (defaults to: 0.0) —

    initial velocity (default: 0.0)

  • on_complete (Symbol, nil) (defaults to: nil) —

    event tag fired when settled



50
51
52
53
54
55
 
# File 'lib/plushie/animation/spring.rb', line 50

def initialize(
  to:, from: nil, stiffness: 170, damping: 26, mass: 1.0,
  velocity: 0.0, on_complete: nil
)
  super
end

Instance Attribute Details

#damping ⇒ Object (readonly)

Returns the value of attribute damping

Returns:

  • (Object) —

    the current value of damping



39
40
41
 
# File 'lib/plushie/animation/spring.rb', line 39

def damping
  @damping
end

#from ⇒ Object (readonly)

Returns the value of attribute from

Returns:

  • (Object) —

    the current value of from



39
40
41
 
# File 'lib/plushie/animation/spring.rb', line 39

def from
  @from
end

#mass ⇒ Object (readonly)

Returns the value of attribute mass

Returns:

  • (Object) —

    the current value of mass



39
40
41
 
# File 'lib/plushie/animation/spring.rb', line 39

def mass
  @mass
end

#on_complete ⇒ Object (readonly)

Returns the value of attribute on_complete

Returns:

  • (Object) —

    the current value of on_complete



39
40
41
 
# File 'lib/plushie/animation/spring.rb', line 39

def on_complete
  @on_complete
end

#stiffness ⇒ Object (readonly)

Returns the value of attribute stiffness

Returns:

  • (Object) —

    the current value of stiffness



39
40
41
 
# File 'lib/plushie/animation/spring.rb', line 39

def stiffness
  @stiffness
end

#to ⇒ Object (readonly)

Returns the value of attribute to

Returns:

  • (Object) —

    the current value of to



39
40
41
 
# File 'lib/plushie/animation/spring.rb', line 39

def to
  @to
end

#velocity ⇒ Object (readonly)

Returns the value of attribute velocity

Returns:

  • (Object) —

    the current value of velocity



39
40
41
 
# File 'lib/plushie/animation/spring.rb', line 39

def velocity
  @velocity
end

Class Method Details

.build(**opts) ⇒ Spring

Create a spring with optional preset expansion.

Parameters:

  • opts (Hash) —

    spring options

Options Hash (**opts):

  • :to (Object) —

    target value (required)

  • :preset (Symbol) —

    named preset (:gentle, :bouncy, etc.)

Returns:

Raises:

  • (ArgumentError) 


72
73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/plushie/animation/spring.rb', line 72

def self.build(**opts)
  raise ArgumentError, "spring requires a :to value" unless opts.key?(:to)

  if (preset = opts.delete(:preset))
    values = SPRING_PRESETS.fetch(preset) do
      raise ArgumentError,
        "unknown spring preset #{preset.inspect}. " \
        "Available: #{SPRING_PRESETS.keys.inspect}"
    end
    opts = values.merge(opts)
  end

  new(**opts)
end

Instance Method Details

#to_wire ⇒ Hash

Returns wire-ready descriptor map.

Returns:

  • (Hash) —

    wire-ready descriptor map



58
59
60
61
62
63
64
 
# File 'lib/plushie/animation/spring.rb', line 58

def to_wire
  h = {type: "spring", to: to, stiffness: stiffness, damping: damping, mass: mass}
  h[:from] = from unless from.nil?
  h[:velocity] = velocity unless velocity == 0.0
  h[:on_complete] = on_complete.to_s if on_complete
  h
end