Allow snap() util to use "radius" without an array of values

[cmal]

Been getting a lot of use out the new GSAP utils and I love them.

 

I did run into a use-case with the snap() util that doesn't seem to be covered, and it seems like something that would be broadly useful. So consider this a feature request.

 

I'd like the ability to use the radius parameter without needing to provide an array of values. For instance:

 

gsap.utils.snap({ value: 500, radius: 100}, x);

 

 

For examples of expected behavior:

 

• If x is 400, it would snap to the closest increment of 500, which is 500
• If x is 300, it wouldn't snap to any value, because it isn't within the radius (100) of any increment of 500
• If x is 950, it would snap to the closest increment of 500, which is 1000

 

Perhaps this was omitted for performance reasons or something similar, but this is how I'd most likely use the radius property the majority of the time if it was an option.

 

Thanks!

[ZachSaucier]

Hey cmal, thanks for posting.

 

This is a good feature request! I don't think it'd be too hard to add but we will wait to hear from @GreenSock and what he has to say. Maybe it could be named snapIncrement like what it's called in the docs.

 

In the mean time you could easily create an array of values if you knew a max range:

let arr = [];
for(let i = 0; i < 10; i++) {
  arr.push(500 * i);
}
gsap.utils.snap({ values: arr, radius: 100}, 900); // returns 1000

Or do that the first time and just copy the generated array into your code so it doesn't have to process it every time.

[GreenSock]

What if it was just called "increment"? It seems more concise and plenty clear. 

gsap.utils.snap({ increment:500, radius: 100}, 350);

Got any other ideas API-wise? 

 

I've experimented with adding it in the latest beta, but I'm not 100% sure it'll be in the final yet. Curious to hear if others find this compelling and worth the kb. https://s3-us-west-2.amazonaws.com/s.cdpn.io/16327/gsap-latest-beta.min.js

[cmal]

I like increment. 

[OSUblake]

13 hours ago, GreenSock said:

Curious to hear if others find this compelling and worth the kb.

 

I don't have strong feelings either way, but I can see how this might be useful for interactive stuff, like dragging. 

 

[GreenSock]

Do ya'all prefer "increment" or "snap"?

snap({increment: 500, radius: 100});

// - OR -

snap({snap: 500, radius: 100});

 

[cmal]

While snap is obviously a lot shorter, I don't think it communicates that the value repeats as clearly as increment. And on a much more subjective level, seeing the word snap twice that close to each other in the same function feels weird.

[GreenSock]

I tend to agree. The only other idea I had was to use "value" for BOTH array-based and increment-based, but that's technically an API change (since currently it's "values" with an "s" for array-based stuff):

snap({value: 500, radius: 100});

snap({value: [500, 1200, 4000], radius: 100});

But I think I like "increment" (for snapping increments) and "values" (for arrays) more. Just floating ideas out there to see if something sticks better with the community before finalizing things. 

[cmal]

For what its worth…

 

When I was first trying things out, I thought that maybe what I was looking for was actually supported but undocumented, so the first thing I did was try both of the following:

snap({value: 500, radius: 100});

snap({values: 500, radius: 100});

That being said, if I was coming in totally fresh I'm not sure I'd look at snap({value: 500, radius: 100}) and assume that meant that it would snap to any increment of 500 – I'd probably assume it meant that it would only snap to a value of 500 and only if it was within 100 of it (400 – 600).

 

I think this is probably a much bigger API change and therefore rules it out, but this was the most intuitive syntax to me when I was first thinking about this:

 

snap(500, { radius: 100});

It looks similar to the default usage of the function, which uses incrementing values, so it is familiar in that regard, and it treats the radius as an option that you just mix into the function. I think for that to work you'd have to significantly change the API so that the first parameter could alternatively be an array, which would make the function consistent when used with either single incrementing values or an array of values. But that's a pretty big change.

[OSUblake]

5 hours ago, cmal said:

 

snap(500, { radius: 100});

It looks similar to the default usage of the function, which uses incrementing values, so it is familiar in that regard, and it treats the radius as an option that you just mix into the function. I think for that to work you'd have to significantly change the API so that the first parameter could alternatively be an array, which would make the function consistent when used with either single incrementing values or an array of values. But that's a pretty big change.

 

I like this idea, but it requires reworking the API.

 

increment would be my second choice. 

 

[GreenSock]

Yeah, I'm reluctant to make such a significant change to the API at this point so I'm inclined to go with "increment" unless anyone has objections. 

[cmal]

Thumbs up for increment