feat: override source and velocity in snapTo

Author: stipsan

README.md

@@ -195,7 +195,7 @@ Fires whenever there's been a window resize event, or if the header, footer or c
 
 #### SNAP
 
-Type: `{ source: 'dragging' | 'custom' }`
+Type: `{ source: 'dragging' | 'custom' | string }`
 
 Fired after dragging ends, or when calling `ref.snapTo`, and a transition to a valid snap point is happening.
 
@@ -205,7 +205,7 @@ Fired after dragging ends, or when calling `ref.snapTo`, and a transition to a v
 function Example() {
   return (
     <BottomSheet
-      onSpringStart={async (event) => {
+      onSpringStart={(event) => {
         if (event.type === 'SNAP' && event.source === 'dragging') {
           console.log('Starting a spring animation to user selected snap point')
         }
@@ -215,6 +215,33 @@ function Example() {
 }
 ```
 
+When using `snapTo` it's possible to use a different `source` than `'custom'`:
+
+```jsx
+function Example() {
+  const sheetRef = useRef()
+  return (
+    <BottomSheet
+      ref={sheetRef}
+      snapPoints={({ minHeight, maxHeight }) => [minHeight, maxHeight]}
+      onSpringEnd={(event) => {
+        if (event.type === 'SNAP' && event.source === 'snap-to-bottom') {
+          console.log(
+            'Just finished an imperativ transition to the bottom snap point'
+          )
+        }
+      }}
+    >
+      <button
+        onClick={() => sheetRef.current.snapTo(0, { source: 'snap-to-bottom' })}
+      >
+        Snap to bottom
+      </button>
+    </BottomSheet>
+  )
+}
+```
+
 ### onSpringEnd
 
 Type: `(event: SpringEvent) => void`
@@ -242,7 +269,7 @@ export default function Example() {
 
 ### snapTo
 
-Type: `(numberOrCallback: number | (state => number)) => void`
+Type: `(numberOrCallback: number | (state => number)) => void, options?: {source?: string, velocity?: number}`
 
 Same signature as the `defaultSnap` prop, calling it will animate the sheet to the new snap point you return. You can either call it with a number, which is the height in px (it'll select the closest snap point that matches your value): `ref.current.snapTo(200)`. Or:
 
@@ -255,6 +282,16 @@ ref.current.snapTo(({ // Showing all the available props
 )
 ```
 
+There's an optional second argument you can use to override `event.source`, as well as changing the `velocity`:
+
+```js
+ref.current.snapTo(({ snapPoints }) => Math.min(...snapPoints), {
+  // Each property is optional, here showing their default values
+  source: 'custom',
+  velocity: 1,
+})
+```
+
 # Credits
 
 - Play icon used on frame overlays: [font-awesome](https://fontawesome.com/icons/play-circle?style=regular)

src/BottomSheet.tsx

@@ -390,9 +390,13 @@ export const BottomSheet = React.forwardRef<
   useImperativeHandle(
     forwardRef,
     () => ({
-      snapTo: (numberOrCallback) => {
+      snapTo: (numberOrCallback, { velocity = 1, source = 'custom' } = {}) => {
         send('SNAP', {
-          payload: { y: findSnapRef.current(numberOrCallback), velocity: 1 },
+          payload: {
+            y: findSnapRef.current(numberOrCallback),
+            velocity,
+            source,
+          },
         })
       },
     }),

src/types.ts

@@ -142,8 +142,13 @@ export interface RefHandles {
   /**
    * When given a number it'll find the closest snap point, so you don't need to know the exact value,
    * Use the callback method to access what snap points you can choose from.
+   *
+   * Use the second argument for advanced settings like:
+   * `source: string` which is passed to onSpring events, and is 'custom' by default
+   * `velocity: number` which is 1 by default, adjust it to control the speed of the spring transition to the new snap point
    */
   snapTo: (
-    numberOrCallback: number | ((state: defaultSnapProps) => number)
+    numberOrCallback: number | ((state: defaultSnapProps) => number),
+    options?: { source?: string; velocity?: number }
   ) => void
 }