motion-v 0.5.0-beta.1 → 0.5.0

package/dist/src/features/gestures/drag/types.d.ts

@@ -1,67 +1,130 @@
-import { VariantLabels } from '../../../types';
-export interface BoundingBox {
-    top: number;
-    right: number;
-    bottom: number;
-    left: number;
+import { DragControls } from './use-drag-controls';
+import { Axis, BoundingBox, DragElastic, InertiaOptions, PanInfo } from 'framer-motion';
+export interface ResolvedConstraints {
+    x: Partial<Axis>;
+    y: Partial<Axis>;
 }
-type DragElastic = boolean | number | Partial<BoundingBox>;
-export interface DragOptions {
+/**
+ * @public
+ */
+export interface DragHandlers {
     /**
-     * Enable dragging for this element. Set to `false` by default.
-     * Set `true` to drag in both directions.
-     * Set `"x"` or `"y"` to only drag in a specific direction.
+     * Callback function that fires when dragging starts.
      *
-     * ```template
-     * <Motion drag="x" />
+     * ```jsx
+     * <motion.div
+     *   drag
+     *   onDragStart={
+     *     (event, info) => console.log(info.point.x, info.point.y)
+     *   }
+     * />
      * ```
+     *
+     * @public
      */
-    drag?: boolean | 'x' | 'y';
+    onDragStart?: (event: MouseEvent | TouchEvent | PointerEvent, info: PanInfo) => void;
+    /**
+     * Callback function that fires when dragging ends.
+     *
+     * ```jsx
+     * <motion.div
+     *   drag
+     *   onDragEnd={
+     *     (event, info) => console.log(info.point.x, info.point.y)
+     *   }
+     * />
+     * ```
+     *
+     * @public
+     */
+    onDragEnd?: (event: MouseEvent | TouchEvent | PointerEvent, info: PanInfo) => void;
     /**
-     * If `true`, the drag direction will be locked to the initial drag direction.
-     * Set to `false` by default.
+     * Callback function that fires when the component is dragged.
      *
-     * ```template
-     * <Motion dragOptions="{ directionLock: true, drag: 'x' }" />
+     * ```jsx
+     * <motion.div
+     *   drag
+     *   onDrag={
+     *     (event, info) => console.log(info.point.x, info.point.y)
+     *   }
+     * />
      * ```
+     *
+     * @public
      */
-    directionLock?: boolean;
+    onDrag?: (event: MouseEvent | TouchEvent | PointerEvent, info: PanInfo) => void;
     /**
-     * Allows drag gesture propagation to child components. Set to `false` by
-     * default.
+     * Callback function that fires a drag direction is determined.
      *
-     * ```template
-     * <Motion dragOptions="{ propagation: true, drag: 'x' }" />
+     * ```jsx
+     * <motion.div
+     *   drag
+     *   dragDirectionLock
+     *   onDirectionLock={axis => console.log(axis)}
+     * />
      * ```
+     *
+     * @public
      */
-    propagation?: boolean;
+    onDirectionLock?: (axis: 'x' | 'y') => void;
     /**
-     * Applies constraints on the permitted draggable area.
+     * Callback function that fires when drag momentum/bounce transition finishes.
      *
-     * It can accept an object of optional `top`, `left`, `right`, and `bottom` values, measured in pixels.
-     * This will define a distance the named edge of the draggable component.
+     * ```jsx
+     * <motion.div
+     *   drag
+     *   onDragTransitionEnd={() => console.log('Drag transition complete')}
+     * />
+     * ```
      *
-     * Alternatively, it can accept a `ref` to another component created with React's `useRef` hook.
-     * This `ref` should be passed both to the draggable component's `dragConstraints` prop, and the `ref`
-     * of the component you want to use as constraints.
+     * @public
+     */
+    onDragTransitionEnd?: () => void;
+    /**
+     * If `dragConstraints` is set to a React ref, this callback will call with the measured drag constraints.
      *
-     * ```template
-     * // In pixels
-     * <Motion dragOptions="{ constraints: { left: 0, right: 300 }, drag: 'x' }" />
+     * @public
+     */
+    onMeasureDragConstraints?: (constraints: BoundingBox) => BoundingBox | void;
+}
+export interface DragProps extends DragHandlers {
+    /**
+     * Enable dragging for this element. Set to `false` by default.
+     * Set `true` to drag in both directions.
+     * Set `"x"` or `"y"` to only drag in a specific direction.
      *
-     * // As a ref to another component
-     * const MyComponent = () => {
-     *   const constraintsRef = ref()
+     * ```jsx
+     * <motion.div drag="x" />
+     * ```
+     */
+    drag?: boolean | 'x' | 'y';
+    /**
+     * If true, element will snap back to its origin when dragging ends.
      *
-     *   return (
-     *     <div ref={constraintsRef}>
-     *       <Motion dragOptions="{ constraints: constraintsRef, drag: 'x' }" />
-     *     </div>
-     *   )
-     * }
+     * Enabling this is the equivalent of setting all `dragConstraints` axes to `0`
+     * with `dragElastic={1}`, but when used together `dragConstraints` can define
+     * a wider draggable area and `dragSnapToOrigin` will ensure the element
+     * animates back to its origin on release.
+     */
+    dragSnapToOrigin?: boolean;
+    /**
+     * If `true`, this will lock dragging to the initially-detected direction. Defaults to `false`.
+     *
+     * ```jsx
+     * <motion.div drag dragDirectionLock />
+     * ```
+     */
+    dragDirectionLock?: boolean;
+    /**
+     * Allows drag gesture propagation to child components. Set to `false` by
+     * default.
+     *
+     * ```jsx
+     * <motion.div drag="x" dragPropagation />
      * ```
      */
-    constraints?: false | Partial<BoundingBox> | HTMLElement;
+    dragPropagation?: boolean;
+    dragConstraints?: false | Partial<BoundingBox> | HTMLElement;
     /**
      * The degree of movement allowed outside constraints. 0 = no movement, 1 =
      * full movement.
@@ -71,23 +134,32 @@ export interface DragOptions {
      * By passing an object of `top`/`right`/`bottom`/`left`, individual values can be set
      * per constraint. Any missing values will be set to `0`.
      *
-     * ```template
-     * <Motion dragOptions="{ dragElastic: 0.2, constraints: { left: 0, right: 300 }, drag: 'x' }" />
+     * ```jsx
+     * <motion.div
+     *   drag
+     *   dragConstraints={{ left: 0, right: 300 }}
+     *   dragElastic={0.2}
+     * />
      * ```
      */
-    elastic?: DragElastic;
+    dragElastic?: DragElastic;
     /**
      * Apply momentum from the pan gesture to the component when dragging
      * finishes. Set to `true` by default.
      *
-     * ```template
-     * <Motion dragOptions="{ dragMomentum: false, constraints: { left: 0, right: 300 }, drag: 'x' }" />
+     * ```jsx
+     * <motion.div
+     *   drag
+     *   dragConstraints={{ left: 0, right: 300 }}
+     *   dragMomentum={false}
+     * />
      * ```
      */
-    momentum?: boolean;
+    dragMomentum?: boolean;
     /**
      * Allows you to change dragging inertia parameters.
      * When releasing a draggable Frame, an animation with type `inertia` starts. The animation is based on your dragging velocity. This property allows you to customize it.
+     * See {@link https://framer.com/api/animation/#inertia | Inertia} for all properties you can use.
      *
      * ```jsx
      * <motion.div
@@ -96,6 +168,33 @@ export interface DragOptions {
      * />
      * ```
      */
+    dragTransition?: InertiaOptions;
+    /**
+     * By default, if `drag` is defined on a component then an event listener will be attached
+     * to automatically initiate dragging when a user presses down on it.
+     *
+     * By setting `dragListener` to `false`, this event listener will not be created.
+     *
+     * ```jsx
+     * const dragControls = useDragControls()
+     *
+     * function startDrag(event) {
+     *   dragControls.start(event, { snapToCursor: true })
+     * }
+     *
+     * return (
+     *   <>
+     *     <div onPointerDown={startDrag} />
+     *     <motion.div
+     *       drag="x"
+     *       dragControls={dragControls}
+     *       dragListener={false}
+     *     />
+     *   </>
+     * )
+     * ```
+     */
+    dragListener?: boolean;
     /**
      * Usually, dragging is initiated by pressing down on a component and moving it. For some
      * use-cases, for instance clicking at an arbitrary point on a video scrubber, we
@@ -120,25 +219,5 @@ export interface DragOptions {
      * )
      * ```
      */
-    /**
-     * If true, element will snap back to its origin when dragging ends.
-     *
-     * Enabling this is the equivalent of setting all `dragConstraints` axes to `0`
-     * with `dragElastic={1}`, but when used together `dragConstraints` can define
-     * a wider draggable area and `dragSnapToOrigin` will ensure the element
-     * animates back to its origin on release.
-     */
-    snapToOrigin?: boolean;
-}
-export interface DragProps {
-    /**
-     * Properties or variant label to animate to while the drag gesture is recognised.
-     *
-     * ```jsx
-     * <motion.div whileDrag={{ scale: 1.2 }} />
-     * ```
-     */
-    drag?: VariantLabels;
-    dragOptions?: DragOptions;
+    dragControls?: DragControls;
 }
-export {};

package/dist/src/features/gestures/drag/use-drag-controls.d.ts

@@ -0,0 +1,73 @@
+import { DragControlOptions, VisualElementDragControls } from './VisualElementDragControls';
+/**
+ * Can manually trigger a drag gesture on one or more `drag`-enabled `motion` components.
+ *
+ * ```jsx
+ * const dragControls = useDragControls()
+ *
+ * function startDrag(event) {
+ *   dragControls.start(event, { snapToCursor: true })
+ * }
+ *
+ * return (
+ *   <>
+ *     <div onPointerDown={startDrag} />
+ *     <motion.div drag="x" dragControls={dragControls} />
+ *   </>
+ * )
+ * ```
+ *
+ * @public
+ */
+export declare class DragControls {
+    private componentControls;
+    /**
+     * Subscribe a component's internal `VisualElementDragControls` to the user-facing API.
+     *
+     * @internal
+     */
+    subscribe(controls: VisualElementDragControls): () => void;
+    /**
+     * Start a drag gesture on every `motion` component that has this set of drag controls
+     * passed into it via the `dragControls` prop.
+     *
+     * ```jsx
+     * dragControls.start(e, {
+     *   snapToCursor: true
+     * })
+     * ```
+     *
+     * @param event - PointerEvent
+     * @param options - Options
+     *
+     * @public
+     */
+    start(event: PointerEvent, options?: DragControlOptions): void;
+}
+/**
+ * Usually, dragging is initiated by pressing down on a `motion` component with a `drag` prop
+ * and moving it. For some use-cases, for instance clicking at an arbitrary point on a video scrubber, we
+ * might want to initiate that dragging from a different component than the draggable one.
+ *
+ * By creating a `dragControls` using the `useDragControls` hook, we can pass this into
+ * the draggable component's `dragControls` prop. It exposes a `start` method
+ * that can start dragging from pointer events on other components.
+ *
+ * ```jsx
+ * const dragControls = useDragControls()
+ *
+ * function startDrag(event) {
+ *   dragControls.start(event, { snapToCursor: true })
+ * }
+ *
+ * return (
+ *   <>
+ *     <div onPointerDown={startDrag} />
+ *     <motion.div drag="x" dragControls={dragControls} />
+ *   </>
+ * )
+ * ```
+ *
+ * @public
+ */
+export declare const useDragControls: () => DragControls;

package/dist/src/features/gestures/drag/utils/constraints.d.ts

@@ -0,0 +1,55 @@
+import { ResolvedConstraints } from '../types';
+import { Axis, BoundingBox, Box, DragElastic } from 'framer-motion';
+/**
+ * Apply constraints to a point. These constraints are both physical along an
+ * axis, and an elastic factor that determines how much to constrain the point
+ * by if it does lie outside the defined parameters.
+ */
+export declare function applyConstraints(point: number, { min, max }: Partial<Axis>, elastic?: Axis): number;
+export declare const defaultElastic = 0.35;
+/**
+ * Calculate constraints in terms of the viewport when
+ * defined relatively to the measured bounding box.
+ */
+export declare function calcRelativeConstraints(layoutBox: Box, { top, left, bottom, right }: Partial<BoundingBox>): ResolvedConstraints;
+/**
+ * Calculate constraints in terms of the viewport when defined relatively to the
+ * measured axis. This is measured from the nearest edge, so a max constraint of 200
+ * on an axis with a max value of 300 would return a constraint of 500 - axis length
+ */
+export declare function calcRelativeAxisConstraints(axis: Axis, min?: number, max?: number): Partial<Axis>;
+/**
+ * Accepts a dragElastic prop and returns resolved elastic values for each axis.
+ */
+export declare function resolveDragElastic(dragElastic?: DragElastic): Box;
+export declare function resolveAxisElastic(dragElastic: DragElastic, minLabel: string, maxLabel: string): Axis;
+export declare function resolvePointElastic(dragElastic: DragElastic, label: string): number;
+/**
+ * Rebase the calculated viewport constraints relative to the layout.min point.
+ */
+export declare function rebaseAxisConstraints(layout: Axis, constraints: Partial<Axis>): Partial<Axis>;
+/**
+ * Calculate viewport constraints when defined as another viewport-relative box
+ */
+export declare function calcViewportConstraints(layoutBox: Box, constraintsBox: Box): {
+    x: {
+        min: number;
+        max: number;
+    };
+    y: {
+        min: number;
+        max: number;
+    };
+};
+/**
+ * Calculate viewport constraints when defined as another viewport-relative axis
+ */
+export declare function calcViewportAxisConstraints(layoutAxis: Axis, constraintsAxis: Axis): {
+    min: number;
+    max: number;
+};
+/**
+ * Calculate a transform origin relative to the source axis, between 0-1, that results
+ * in an asthetically pleasing scale/transform needed to project from source to target.
+ */
+export declare function calcOrigin(source: Axis, target: Axis): number;

package/dist/src/features/gestures/drag/utils/is.d.ts

@@ -0,0 +1 @@
+export declare function isHTMLElement(value: any): value is HTMLElement;

package/dist/src/features/gestures/hover/index.d.ts

@@ -0,0 +1,7 @@
+import { MotionState } from '../../../state/motion-state';
+import { Feature } from '../..';
+export declare class HoverGesture extends Feature {
+    isActive(): boolean;
+    constructor(state: MotionState);
+    mount(): void;
+}

package/dist/src/features/gestures/hover/types.d.ts

@@ -0,0 +1,8 @@
+import { Variant } from '../../../types';
+import { EventInfo } from 'framer-motion';
+export type HoverEvent = (event: MouseEvent, info: EventInfo) => void;
+export interface HoverProps {
+    hover?: string | Variant;
+    onHoverStart?: HoverEvent;
+    onHoverEnd?: HoverEvent;
+}

package/dist/src/features/gestures/in-view/index.d.ts

@@ -0,0 +1,7 @@
+import { MotionState } from '../../../state/motion-state';
+import { Feature } from '../..';
+export declare class InViewGesture extends Feature {
+    isActive(): boolean;
+    constructor(state: MotionState);
+    mount(): void;
+}

package/dist/src/features/gestures/in-view/types.d.ts

@@ -0,0 +1,18 @@
+import { Variant } from '../../../types';
+type MarginValue = `${number}${'px' | '%'}`;
+type MarginType = MarginValue | `${MarginValue} ${MarginValue}` | `${MarginValue} ${MarginValue} ${MarginValue}` | `${MarginValue} ${MarginValue} ${MarginValue} ${MarginValue}`;
+export interface InViewOptions {
+    root?: Element | Document;
+    margin?: MarginType;
+    amount?: 'some' | 'all' | number;
+}
+type ViewportEventHandler = (entry: IntersectionObserverEntry | null) => void;
+export interface InViewProps {
+    inViewOptions?: InViewOptions & {
+        once?: boolean;
+    };
+    inView?: string | Variant;
+    onViewportEnter?: ViewportEventHandler;
+    onViewportLeave?: ViewportEventHandler;
+}
+export {};

package/dist/src/features/gestures/pan/PanSession.d.ts

@@ -0,0 +1,139 @@
+import { Point, TransformPoint } from 'framer-motion';
+/**
+ * Passed in to pan event handlers like `onPan` the `PanInfo` object contains
+ * information about the current state of the tap gesture such as its
+ * `point`, `delta`, `offset` and `velocity`.
+ *
+ * ```jsx
+ * <motion.div onPan={(event, info) => {
+ *   console.log(info.point.x, info.point.y)
+ * }} />
+ * ```
+ *
+ * @public
+ */
+export interface PanInfo {
+    /**
+     * Contains `x` and `y` values for the current pan position relative
+     * to the device or page.
+     *
+     * ```jsx
+     * function onPan(event, info) {
+     *   console.log(info.point.x, info.point.y)
+     * }
+     *
+     * <motion.div onPan={onPan} />
+     * ```
+     *
+     * @public
+     */
+    point: Point;
+    /**
+     * Contains `x` and `y` values for the distance moved since
+     * the last event.
+     *
+     * ```jsx
+     * function onPan(event, info) {
+     *   console.log(info.delta.x, info.delta.y)
+     * }
+     *
+     * <motion.div onPan={onPan} />
+     * ```
+     *
+     * @public
+     */
+    delta: Point;
+    /**
+     * Contains `x` and `y` values for the distance moved from
+     * the first pan event.
+     *
+     * ```jsx
+     * function onPan(event, info) {
+     *   console.log(info.offset.x, info.offset.y)
+     * }
+     *
+     * <motion.div onPan={onPan} />
+     * ```
+     *
+     * @public
+     */
+    offset: Point;
+    /**
+     * Contains `x` and `y` values for the current velocity of the pointer, in px/ms.
+     *
+     * ```jsx
+     * function onPan(event, info) {
+     *   console.log(info.velocity.x, info.velocity.y)
+     * }
+     *
+     * <motion.div onPan={onPan} />
+     * ```
+     *
+     * @public
+     */
+    velocity: Point;
+}
+export type PanHandler = (event: Event, info: PanInfo) => void;
+interface PanSessionHandlers {
+    onSessionStart: PanHandler;
+    onStart: PanHandler;
+    onMove: PanHandler;
+    onEnd: PanHandler;
+    onSessionEnd: PanHandler;
+    resumeAnimation: () => void;
+}
+interface PanSessionOptions {
+    transformPagePoint?: TransformPoint;
+    contextWindow?: (Window & typeof globalThis) | null;
+    dragSnapToOrigin?: boolean;
+}
+/**
+ * @internal
+ */
+export declare class PanSession {
+    /**
+     * @internal
+     */
+    private history;
+    /**
+     * @internal
+     */
+    private startEvent;
+    /**
+     * @internal
+     */
+    private lastMoveEvent;
+    /**
+     * @internal
+     */
+    private lastMoveEventInfo;
+    /**
+     * @internal
+     */
+    private transformPagePoint?;
+    /**
+     * @internal
+     */
+    private handlers;
+    /**
+     * @internal
+     */
+    private removeListeners;
+    /**
+     * For determining if an animation should resume after it is interupted
+     *
+     * @internal
+     */
+    private dragSnapToOrigin;
+    /**
+     * @internal
+     */
+    private contextWindow;
+    constructor(event: PointerEvent, handlers: Partial<PanSessionHandlers>, { transformPagePoint, contextWindow, dragSnapToOrigin }?: PanSessionOptions);
+    private updatePoint;
+    private handlePointerMove;
+    private handlePointerUp;
+    updateHandlers(handlers: Partial<PanSessionHandlers>): void;
+    end(): void;
+}
+export {};

package/dist/src/features/gestures/pan/index.d.ts

@@ -0,0 +1,16 @@
+import { PanInfo } from './PanSession';
+import { Feature } from '../../feature';
+export declare class PanGesture extends Feature {
+    private session?;
+    private removePointerDownListener;
+    onPointerDown(pointerDownEvent: PointerEvent): void;
+    createPanHandlers(): {
+        onSessionStart: (event: PointerEvent, info: PanInfo) => void;
+        onStart: (event: PointerEvent, info: PanInfo) => void;
+        onMove: (event: any, info: any) => void;
+        onEnd: (event: PointerEvent, info: PanInfo) => void;
+    };
+    mount(): void;
+    update(): void;
+    unmount(): void;
+}

package/dist/src/features/gestures/pan/types.d.ts

@@ -0,0 +1,7 @@
+import { PanInfo } from './PanSession';
+export interface PanProps {
+    onPanSessionStart?: (event: PointerEvent, info: PanInfo) => void;
+    onPanStart?: (event: PointerEvent, info: PanInfo) => void;
+    onPan?: (event: PointerEvent, info: PanInfo) => void;
+    onPanEnd?: (event: PointerEvent, info: PanInfo) => void;
+}

package/dist/src/features/gestures/press/index.d.ts

@@ -0,0 +1,9 @@
+import { MotionState } from '../../../state/motion-state';
+import { Feature } from '../..';
+import { EventInfo } from 'framer-motion';
+export declare function extractEventInfo(event: PointerEvent): EventInfo;
+export declare class PressGesture extends Feature {
+    isActive(): boolean;
+    constructor(state: MotionState);
+    mount(): void;
+}

package/dist/src/features/gestures/press/types.d.ts

@@ -0,0 +1,13 @@
+import { Variant } from '../../../types';
+import { EventInfo } from 'framer-motion';
+export type PressEvent = (event: PointerEvent, info: EventInfo) => void;
+export interface PressProps {
+    /**
+     * If `true`, the press gesture will attach its start listener to window.
+     */
+    globalPressTarget?: boolean;
+    press?: string | Variant;
+    onPressStart?: PressEvent;
+    onPress?: PressEvent;
+    onPressCancel?: PressEvent;
+}

package/dist/src/features/index.d.ts

@@ -1,6 +1,6 @@
 export * from './feature';
-export * from './events';
 export * from './gestures';
 export * from './svg';
 export * from './layout/layout';
+export * from './gestures/pan';
 export * from './feature-manager';

package/dist/src/features/layout/layout.d.ts

@@ -1,10 +1,11 @@
 import { Feature } from '../feature';
 import { MotionState } from '../../state/motion-state';
-import { LayoutGroupState } from '../../components/context';
 export declare class LayoutFeature extends Feature {
-    layoutGroup: LayoutGroupState;
     constructor(state: MotionState);
+    beforeUpdate(): void;
     update(): void;
+    beforeMount(): void;
     mount(): void;
+    beforeUnmount(): void;
     unmount(): void;
 }

package/dist/src/features/layout/projection.d.ts

@@ -0,0 +1,7 @@
+import { Feature } from '../feature';
+export declare class ProjectionFeature extends Feature {
+    constructor(state: any);
+    initProjection(): void;
+    beforeMount(): void;
+    mount(): void;
+}

package/dist/src/index.d.ts

@@ -11,3 +11,4 @@ export * from './constants';
 export * from './types';
 export * from './animation';
 export * from './utils';
+export type { PanInfo } from './features/gestures/pan/PanSession';