move AllDragListenerOptions to its own file, see phetsims/scenery-phe…

…t#858

js/imports.ts

@@ -237,6 +237,7 @@ export type { PressListenerOptions, PressListenerDOMEvent, PressListenerEvent, P
 export { default as FireListener } from './listeners/FireListener.js';
 export type { FireListenerOptions } from './listeners/FireListener.js';
 export { default as DragListener } from './listeners/DragListener.js';
+export type { AllDragListenerOptions } from './listeners/AllDragListenerOptions.js';
 export type { DragListenerOptions, PressedDragListener } from './listeners/DragListener.js';
 
 export { default as MultiListenerPress } from './listeners/MultiListenerPress.js';

js/listeners/AllDragListenerOptions.ts

@@ -0,0 +1,49 @@
+// Copyright 2024, University of Colorado Boulder
+
+/**
+ * Options used by many drag listeners in scenery. At this time, that includes DragListener and KeyboardDragListener.
+ *
+ * @author Jonathan Olson <[email protected]>
+ * @author Michael Kauzmann (PhET Interactive Simulations)
+ * @author Jesse Greenberg (PhET Interactive Simulations)
+ */
+
+import Vector2 from '../../../dot/js/Vector2.js';
+import { SceneryListenerCallback, SceneryListenerNullableCallback } from '../imports.js';
+import TProperty from '../../../axon/js/TProperty.js';
+import Transform3 from '../../../dot/js/Transform3.js';
+import TReadOnlyProperty from '../../../axon/js/TReadOnlyProperty.js';
+import Bounds2 from '../../../dot/js/Bounds2.js';
+
+type MapPosition = ( point: Vector2 ) => Vector2;
+
+export type AllDragListenerOptions<Listener, DOMEvent extends Event> = {
+
+  // Called when the drag is started.
+  start?: SceneryListenerCallback<Listener, DOMEvent> | null;
+
+  // Called when this listener is dragged.
+  drag?: SceneryListenerCallback<Listener, DOMEvent> | null;
+
+  // Called when the drag is ended.
+  // NOTE: This will also be called if the drag is ended due to being interrupted or canceled.
+  end?: SceneryListenerNullableCallback<Listener, DOMEvent> | null;
+
+  // If provided, it will be synchronized with the drag position in the model coordinate frame. The optional transform
+  // is applied.
+  positionProperty?: Pick<TProperty<Vector2>, 'value'> | null;
+
+  // If provided, this will be used to convert between the parent (view) and model coordinate frames. Most useful
+  // when you also provide a positionProperty.
+  transform?: Transform3 | TReadOnlyProperty<Transform3> | null;
+
+  // If provided, the model position will be constrained to these bounds.
+  dragBoundsProperty?: TReadOnlyProperty<Bounds2 | null> | null;
+
+  // If provided, this allows custom mapping from the desired position (i.e. where the pointer is, or where the
+  // KeyboardDragListener will set the position) to the actual position that will be used.
+  mapPosition?: null | MapPosition;
+
+  // If true, the target Node will be translated during the drag operation.
+  translateNode?: boolean;
+};

js/listeners/DragListener.ts

@@ -79,9 +79,8 @@ import RequiredOption from '../../../phet-core/js/types/RequiredOption.js';
 import EventType from '../../../tandem/js/EventType.js';
 import PhetioObject from '../../../tandem/js/PhetioObject.js';
 import Tandem from '../../../tandem/js/Tandem.js';
-import { Node, Pointer, PressedPressListener, PressListener, PressListenerDOMEvent, PressListenerEvent, PressListenerOptions, scenery, SceneryEvent, TInputListener, TransformTracker } from '../imports.js';
+import { AllDragListenerOptions, Node, Pointer, PressedPressListener, PressListener, PressListenerDOMEvent, PressListenerEvent, PressListenerOptions, scenery, SceneryEvent, TInputListener, TransformTracker } from '../imports.js';
 import Property from '../../../axon/js/Property.js';
-import { AllDragListenerOptions } from './RichDragListener.js';
 
 // Scratch vectors used to prevent allocations
 const scratchVector2A = new Vector2( 0, 0 );
@@ -195,8 +194,13 @@ export default class DragListener extends PressListener implements TInputListene
   public constructor( providedOptions?: DragListenerOptions<PressedDragListener> ) {
     const options = optionize<DragListenerOptions<PressedDragListener>, SelfOptions<PressedDragListener>, PressListenerOptions<PressedDragListener>>()( {
       positionProperty: null,
+
+      // start is preferred over passing press(), as the drag start hasn't been fully processed at that point.
       start: null,
+
+      // end is preferred over passing release(), as the drag start hasn't been fully processed at that point.
       end: null,
+
       drag: _.noop,
       transform: null,
       dragBoundsProperty: null,

js/listeners/KeyboardDragListener.ts

@@ -45,7 +45,7 @@ import Transform3 from '../../../dot/js/Transform3.js';
 import Vector2 from '../../../dot/js/Vector2.js';
 import EventType from '../../../tandem/js/EventType.js';
 import Tandem from '../../../tandem/js/Tandem.js';
-import { EnglishKey, globalKeyStateTracker, KeyboardListener, KeyboardListenerOptions, KeyboardUtils, KeyDescriptor, KeyDescriptorOptions, Node, PDOMPointer, scenery, SceneryEvent, SceneryListenerCallback, SceneryListenerNullableCallback, TInputListener } from '../imports.js';
+import { AllDragListenerOptions, EnglishKey, globalKeyStateTracker, KeyboardListener, KeyboardListenerOptions, KeyboardUtils, KeyDescriptor, KeyDescriptorOptions, Node, PDOMPointer, scenery, SceneryEvent, SceneryListenerCallback, SceneryListenerNullableCallback, TInputListener } from '../imports.js';
 import TProperty from '../../../axon/js/TProperty.js';
 import optionize, { EmptySelfOptions } from '../../../phet-core/js/optionize.js';
 import TReadOnlyProperty from '../../../axon/js/TReadOnlyProperty.js';
@@ -58,7 +58,6 @@ import platform from '../../../phet-core/js/platform.js';
 import StrictOmit from '../../../phet-core/js/types/StrictOmit.js';
 import { EnabledComponentOptions } from '../../../axon/js/EnabledComponent.js';
 import stepTimer from '../../../axon/js/stepTimer.js';
-import { AllDragListenerOptions } from './RichDragListener.js';
 
 // 'shift' is not included in any list of keys because we don't want the KeyboardListener to be 'pressed' when only
 // the shift key is down. State of the shift key is tracked by the globalKeyStateTracker.

js/listeners/RichDragListener.ts

@@ -31,59 +31,12 @@
  * @author Jesse Greenberg
  */
 
-import TProperty from '../../../axon/js/TProperty.js';
-import { DragListener, DragListenerOptions, Hotkey, KeyboardDragListener, KeyboardDragListenerCallback, KeyboardDragListenerNullableCallback, KeyboardDragListenerOptions, PressedDragListener, PressListenerCallback, PressListenerDOMEvent, PressListenerEvent, PressListenerNullableCallback, scenery, SceneryEvent, SceneryListenerCallback, SceneryListenerNullableCallback, TInputListener } from '../imports.js';
-import Vector2 from '../../../dot/js/Vector2.js';
-import Transform3 from '../../../dot/js/Transform3.js';
+import { AllDragListenerOptions, DragListener, DragListenerOptions, Hotkey, KeyboardDragListener, KeyboardDragListenerCallback, KeyboardDragListenerNullableCallback, KeyboardDragListenerOptions, PressedDragListener, PressListenerCallback, PressListenerDOMEvent, PressListenerEvent, PressListenerNullableCallback, scenery, SceneryEvent, TInputListener } from '../imports.js';
 import TReadOnlyProperty from '../../../axon/js/TReadOnlyProperty.js';
-import Bounds2 from '../../../dot/js/Bounds2.js';
 import optionize, { combineOptions } from '../../../phet-core/js/optionize.js';
 import DerivedProperty from '../../../axon/js/DerivedProperty.js';
 import { KeyboardDragListenerDOMEvent } from './KeyboardDragListener.js';
 
-type MapPosition = ( point: Vector2 ) => Vector2;
-
-//  TODO: Is there a better spot for these options? https://github.com/phetsims/scenery-phet/issues/858
-// Options shared between DragListener and KeyboardDragListener
-export type AllDragListenerOptions<Listener, DOMEvent extends Event> = {
-  // TODO: Fix doc to apply to any dragging listener https://github.com/phetsims/scenery-phet/issues/858
-
-  // Called when the drag is started, for any input type. If you want to determine the type of input, you can check
-  // SceneryEvent.isFromPDOM or SceneryEvent.type. If you need a start behavior for a specific form of input,
-  // provide a start callback for that listener's options. It will be called IN ADDITION to this callback.
-  start?: SceneryListenerCallback<Listener, DOMEvent> | null;
-
-  // Called during the drag event, for any input type. If you want to determine the type of input, you can check
-  // SceneryEvent.isFromPDOM or SceneryEvent.type. If you need a drag behavior for a specific form of input,
-  // provide a drag callback for that listener's options. It will be called IN ADDITION to this callback.
-  drag?: SceneryListenerCallback<Listener, DOMEvent> | null;
-
-  // Called when the drag is ended, for any input type. If you want to determine the type of input, you can check
-  // SceneryEvent.isFromPDOM or SceneryEvent.type. If you need an end behavior for a specific form of input,
-  // provide an end callback for that listener's options. It will be called IN ADDITION to this callback. The event
-  // may be null for cases of interruption.
-  end?: SceneryListenerNullableCallback<Listener, DOMEvent> | null;
-
-  // If provided, it will be synchronized with the drag position in the model coordinate frame. The optional transform
-  // is applied.
-  positionProperty?: Pick<TProperty<Vector2>, 'value'> | null;
-
-  // If provided, this will be used to convert between the parent (view) and model coordinate frames. Most useful
-  // when you also provide a positionProperty.
-  transform?: Transform3 | TReadOnlyProperty<Transform3> | null;
-
-  // If provided, the model position will be constrained to these bounds.
-  dragBoundsProperty?: TReadOnlyProperty<Bounds2 | null> | null;
-
-  // If provided, this allows custom mapping from the desired position (i.e. where the pointer is, or where the
-  // KeyboardDragListener will set the position) to the actual position that will be used.
-  mapPosition?: null | MapPosition;
-
-  // If true, the target Node will be translated during the drag operation.
-  translateNode?: boolean;
-};
-
-// Any options in "All" dragging options whill be applied to both the keyboard and pointer dragging listener instances.
 type SelfOptions = AllDragListenerOptions<DragListener | KeyboardDragListener, PressListenerDOMEvent | KeyboardDragListenerDOMEvent> & {
 
   // Additional options for the DragListener, OR any overrides for the DragListener that should
@@ -119,8 +72,21 @@ export default class RichDragListener implements TInputListener {
 
       // RichDragListenerOptions
       positionProperty: null,
+
+      // Called when the drag is started, for any input type. If you want to determine the type of input, you can check
+      // SceneryEvent.isFromPDOM or SceneryEvent.type. If you need a start behavior for a specific form of input,
+      // provide a start callback for that listener's options. It will be called IN ADDITION to this callback.
       start: null,
+
+      // Called when the drag is ended, for any input type. If you want to determine the type of input, you can check
+      // SceneryEvent.isFromPDOM or SceneryEvent.type. If you need an end behavior for a specific form of input,
+      // provide an end callback for that listener's options. It will be called IN ADDITION to this callback. The event
+      // may be null for cases of interruption.
       end: null,
+
+      // Called during the drag event, for any input type. If you want to determine the type of input, you can check
+      // SceneryEvent.isFromPDOM or SceneryEvent.type. If you need a drag behavior for a specific form of input,
+      // provide a drag callback for that listener's options. It will be called IN ADDITION to this callback.
       drag: null,
       transform: null,
       dragBoundsProperty: null,