Merge pull request #984 from framer/feature/individual-drag-elastic

Adding dragElastic as an object

Author: mergetron[bot]

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 Framer Motion adheres to [Semantic Versioning](http://semver.org/).
 
+## [3.9.0] 2021-03-02
+
+### Added
+
+-   `dragElastic` now accepts per-axis elastic settings.
+
 ## [3.8.2] 2021-03-01
 
 ### Fixed

api/framer-motion.api.md

@@ -209,6 +209,9 @@ export class DragControls {
     updateConstraints(): void;
 }
 
+// @public (undocumented)
+export type DragElastic = boolean | number | Partial<BoundingBox2D>;
+
 // @public (undocumented)
 export const DragFeature: MotionFeature;
 
@@ -218,7 +221,7 @@ export interface DraggableProps extends DragHandlers {
     dragConstraints?: false | Partial<BoundingBox2D> | RefObject<Element>;
     dragControls?: DragControls;
     dragDirectionLock?: boolean;
-    dragElastic?: boolean | number;
+    dragElastic?: DragElastic;
     dragListener?: boolean;
     dragMomentum?: boolean;
     dragPropagation?: boolean;

package.json

@@ -1,6 +1,6 @@
 {
     "name": "framer-motion",
-    "version": "3.8.2",
+    "version": "3.9.0",
     "description": "A simple and powerful React animation library",
     "main": "dist/framer-motion.cjs.js",
     "module": "dist/es/index.js",

src/gestures/drag/VisualElementDragControls.ts

@@ -2,7 +2,7 @@ import { RefObject } from "react"
 import { invariant } from "hey-listen"
 import { progress } from "popmotion"
 import { PanSession, AnyPointerEvent, PanInfo } from "../../gestures/PanSession"
-import { DraggableProps, DragHandler } from "./types"
+import { DraggableProps, DragHandler, ResolvedConstraints } from "./types"
 import { Lock, getGlobalLock } from "./utils/lock"
 import { isRefObject } from "../../utils/is-ref-object"
 import { addPointerEvent } from "../../events/use-pointer-event"
@@ -12,16 +12,18 @@ import { TransformPoint2D, AxisBox2D, Point2D } from "../../types/geometry"
 import {
     convertBoundingBoxToAxisBox,
     convertAxisBoxToBoundingBox,
+    axisBox,
 } from "../../utils/geometry"
 import { eachAxis } from "../../utils/each-axis"
 import {
     calcRelativeConstraints,
     calcConstrainedMinPoint,
-    ResolvedConstraints,
     calcViewportConstraints,
     calcPositionFromProgress,
     applyConstraints,
     rebaseAxisConstraints,
+    resolveDragElastic,
+    defaultElastic,
 } from "./utils/constraints"
 import { getBoundingBox } from "../../render/dom/projection/measure"
 import { calcOrigin } from "../../utils/geometry/delta-calc"
@@ -78,6 +80,13 @@ export class VisualElementDragControls {
      */
     private constraints: ResolvedConstraints | false = false
 
+    /**
+     * The per-axis resolved elastic values.
+     *
+     * @internal
+     */
+    private elastic: AxisBox2D = axisBox()
+
     /**
      * A reference to the host component's latest props.
      *
@@ -287,7 +296,7 @@ export class VisualElementDragControls {
     }
 
     resolveDragConstraints() {
-        const { dragConstraints } = this.props
+        const { dragConstraints, dragElastic } = this.props
 
         if (dragConstraints) {
             this.constraints = isRefObject(dragConstraints)
@@ -303,6 +312,8 @@ export class VisualElementDragControls {
             this.constraints = false
         }
 
+        this.elastic = resolveDragElastic(dragElastic!)
+
         /**
          * If we're outputting to external MotionValues, we want to rebase the measured constraints
          * from viewport-relative to component-relative.
@@ -384,9 +395,9 @@ export class VisualElementDragControls {
 
         if (!isDragging) return
 
-        const { dragMomentum, dragElastic, onDragEnd } = this.props
+        const { dragMomentum, onDragEnd } = this.props
 
-        if (dragMomentum || dragElastic) {
+        if (dragMomentum || this.elastic) {
             const { velocity } = info
             this.animateDragEnd(velocity)
         }
@@ -439,22 +450,19 @@ export class VisualElementDragControls {
 
         if (!offset || !axisValue) return
 
-        const { dragElastic } = this.props
         const nextValue = this.originPoint[axis]! + offset[axis]
         const update = this.constraints
             ? applyConstraints(
                   nextValue,
                   this.constraints[axis],
-                  dragElastic as number
+                  this.elastic[axis]
               )
             : nextValue
 
         axisValue.set(update)
     }
 
     updateVisualElementAxis(axis: DragDirection, event: AnyPointerEvent) {
-        const { dragElastic } = this.props
-
         // Get the actual layout bounding box of the element
         const axisLayout = this.visualElement.getLayoutState().layout[axis]
 
@@ -472,7 +480,7 @@ export class VisualElementDragControls {
             axisLength,
             axisProgress,
             this.constraints?.[axis],
-            dragElastic as number
+            this.elastic[axis]
         )
 
         // Update the axis viewport target with this new min and the length
@@ -484,7 +492,7 @@ export class VisualElementDragControls {
         dragDirectionLock = false,
         dragPropagation = false,
         dragConstraints = false,
-        dragElastic = 0.35,
+        dragElastic = defaultElastic,
         dragMomentum = true,
         ...remainingProps
     }: DragControlsProps & MotionProps) {

src/gestures/drag/types.ts

@@ -1,7 +1,7 @@
 import { RefObject } from "react"
 import { PanInfo } from "../PanSession"
 import { Inertia, TargetAndTransition } from "../../types"
-import { BoundingBox2D } from "../../types/geometry"
+import { Axis, BoundingBox2D } from "../../types/geometry"
 import { DragControls } from "./use-drag-controls"
 import { MotionValue } from "../../value"
 import { VariantLabels } from "../../motion/types"
@@ -11,6 +11,18 @@ export type DragHandler = (
     info: PanInfo
 ) => void
 
+export type DragElastic = boolean | number | Partial<BoundingBox2D>
+
+export interface ResolvedConstraints {
+    x: Partial<Axis>
+    y: Partial<Axis>
+}
+
+export interface ResolvedElastic {
+    x: Axis
+    y: Axis
+}
+
 /**
  * @public
  */
@@ -294,7 +306,12 @@ export interface DraggableProps extends DragHandlers {
 
     /**
      * The degree of movement allowed outside constraints. 0 = no movement, 1 =
-     * full movement. Set to `0.5` by default.
+     * full movement.
+     *
+     * Set to `0.5` by default. Can also be set as `false` to disable movement.
+     *
+     * By passing an object of `top`/`right`/`bottom`/`left`, individual values can be set
+     * per constraint. Any missing values will be set to `0`.
      *
      * @library
      *
@@ -316,7 +333,7 @@ export interface DraggableProps extends DragHandlers {
      * />
      * ```
      */
-    dragElastic?: boolean | number
+    dragElastic?: DragElastic
 
     /**
      * Apply momentum from the pan gesture to the component when dragging

src/gestures/drag/utils/__tests__/constraints.test.ts

@@ -5,27 +5,79 @@ import {
     calcViewportAxisConstraints,
     calcPositionFromProgress,
     rebaseAxisConstraints,
+    resolveDragElastic,
 } from "../constraints"
 
+describe("resolveDragElastic", () => {
+    test("Resolves false as 0", () => {
+        expect(resolveDragElastic(false)).toEqual({
+            x: { min: 0, max: 0 },
+            y: { min: 0, max: 0 },
+        })
+    })
+    test("Resolves true as default", () => {
+        expect(resolveDragElastic(true)).toEqual({
+            x: { min: 0.35, max: 0.35 },
+            y: { min: 0.35, max: 0.35 },
+        })
+    })
+
+    test("Resolves number as object filled with number", () => {
+        expect(resolveDragElastic(0.5)).toEqual({
+            x: { min: 0.5, max: 0.5 },
+            y: { min: 0.5, max: 0.5 },
+        })
+    })
+
+    test("Resolves object as object, with default values for missing values", () => {
+        expect(
+            resolveDragElastic({ top: 0.1, left: 0.2, bottom: 0.3, right: 0.4 })
+        ).toEqual({
+            x: { min: 0.2, max: 0.4 },
+            y: { min: 0.1, max: 0.3 },
+        })
+        expect(resolveDragElastic({ top: 0.1, right: 0.4 })).toEqual({
+            x: { min: 0, max: 0.4 },
+            y: { min: 0.1, max: 0 },
+        })
+    })
+})
+
 describe("applyConstraints", () => {
     test("Returns points within the defined constraints", () => {
         expect(applyConstraints(10, { min: 0, max: 20 })).toBe(10)
     })
-    test("Returns points outside the defined constraints when elastic is set to 1", () => {
-        expect(applyConstraints(25, { min: 0, max: 20 }, 1)).toBe(25)
-        expect(applyConstraints(-5, { min: 0, max: 20 }, 1)).toBe(-5)
-    })
-    test("Clamps points outside the defined constraints when elastic is set to 0", () => {
-        expect(applyConstraints(25, { min: 0, max: 20 }, 0)).toBe(20)
-        expect(applyConstraints(-5, { min: 0, max: 20 }, 0)).toBe(0)
-    })
-    test("Applies elastic factor if defined", () => {
-        expect(applyConstraints(25, { min: 0, max: 20 }, 0.5)).toBe(22.5)
-        expect(applyConstraints(-5, { min: 0, max: 20 }, 0.5)).toBe(-2.5)
-        expect(applyConstraints(25, { min: 0, max: 20 }, 1)).toBe(25)
-        expect(applyConstraints(-5, { min: 0, max: 20 }, 1)).toBe(-5)
-        expect(applyConstraints(25, { min: 0, max: 20 }, 0)).toBe(20)
-        expect(applyConstraints(-5, { min: 0, max: 20 }, 0)).toBe(0)
+    test("Applies elastic factor", () => {
+        expect(
+            applyConstraints(25, { min: 0, max: 20 }, { min: 0.5, max: 0.5 })
+        ).toBe(22.5)
+        expect(
+            applyConstraints(25, { min: 0, max: 20 }, { min: 1, max: 0.5 })
+        ).toBe(22.5)
+        expect(
+            applyConstraints(-5, { min: 0, max: 20 }, { min: 0.5, max: 0.5 })
+        ).toBe(-2.5)
+        expect(
+            applyConstraints(-5, { min: 0, max: 20 }, { min: 0.5, max: 1 })
+        ).toBe(-2.5)
+        expect(
+            applyConstraints(25, { min: 0, max: 20 }, { min: 1, max: 1 })
+        ).toBe(25)
+        expect(
+            applyConstraints(-5, { min: 0, max: 20 }, { min: 1, max: 1 })
+        ).toBe(-5)
+        expect(
+            applyConstraints(25, { min: 0, max: 20 }, { min: 0, max: 0 })
+        ).toBe(20)
+        expect(
+            applyConstraints(25, { min: 0, max: 20 }, { min: 1, max: 0 })
+        ).toBe(20)
+        expect(
+            applyConstraints(-5, { min: 0, max: 20 }, { min: 0, max: 0 })
+        ).toBe(0)
+        expect(
+            applyConstraints(-5, { min: 0, max: 20 }, { min: 0, max: 1 })
+        ).toBe(0)
     })
 })
 

src/gestures/drag/utils/constraints.ts

@@ -6,11 +6,7 @@ import {
 } from "../../../types/geometry"
 import { mix } from "popmotion"
 import { calcOrigin } from "../../../utils/geometry/delta-calc"
-
-export interface ResolvedConstraints {
-    x: Partial<Axis>
-    y: Partial<Axis>
-}
+import { DragElastic, ResolvedConstraints } from "../types"
 
 /**
  * Apply constraints to a point. These constraints are both physical along an
@@ -20,14 +16,14 @@ export interface ResolvedConstraints {
 export function applyConstraints(
     point: number,
     { min, max }: Partial<Axis>,
-    elastic?: number
+    elastic?: Axis
 ): number {
     if (min !== undefined && point < min) {
         // If we have a min point defined, and this is outside of that, constrain
-        point = elastic ? mix(min, point, elastic) : Math.max(point, min)
+        point = elastic ? mix(min, point, elastic.min) : Math.max(point, min)
     } else if (max !== undefined && point > max) {
         // If we have a max point defined, and this is outside of that, constrain
-        point = elastic ? mix(max, point, elastic) : Math.min(point, max)
+        point = elastic ? mix(max, point, elastic.max) : Math.min(point, max)
     }
 
     return point
@@ -46,7 +42,7 @@ export function calcConstrainedMinPoint(
     length: number,
     progress: number,
     constraints?: Partial<Axis>,
-    elastic?: number
+    elastic?: Axis
 ): number {
     // Calculate a min point for this axis and apply it to the current pointer
     const min = point - length * progress
@@ -175,3 +171,40 @@ export function rebaseAxisConstraints(
 
     return relativeConstraints
 }
+
+export const defaultElastic = 0.35
+/**
+ * Accepts a dragElastic prop and returns resolved elastic values for each axis.
+ */
+export function resolveDragElastic(dragElastic: DragElastic): AxisBox2D {
+    if (dragElastic === false) {
+        dragElastic = 0
+    } else if (dragElastic === true) {
+        dragElastic = defaultElastic
+    }
+
+    return {
+        x: resolveAxisElastic(dragElastic, "left", "right"),
+        y: resolveAxisElastic(dragElastic, "top", "bottom"),
+    }
+}
+
+export function resolveAxisElastic(
+    dragElastic: DragElastic,
+    minLabel: string,
+    maxLabel: string
+): Axis {
+    return {
+        min: resolvePointElastic(dragElastic, minLabel),
+        max: resolvePointElastic(dragElastic, maxLabel),
+    }
+}
+
+export function resolvePointElastic(
+    dragElastic: DragElastic,
+    label: string
+): number {
+    return typeof dragElastic === "number"
+        ? dragElastic
+        : dragElastic[label] ?? 0
+}

src/index.ts

@@ -129,7 +129,11 @@ export {
 export { EventInfo } from "./events/types"
 export { VisualElementLifecycles } from "./render/utils/lifecycles"
 export { MotionFeature, FeatureProps } from "./motion/features/types"
-export { DraggableProps, DragHandlers } from "./gestures/drag/types"
+export {
+    DraggableProps,
+    DragHandlers,
+    DragElastic,
+} from "./gestures/drag/types"
 export { LayoutProps } from "./motion/features/layout/types"
 export { AnimatePresenceProps } from "./components/AnimatePresence/types"
 export { SharedLayoutProps } from "./components/AnimateSharedLayout/types"