chore(movable): deprecate trigger parameter in favor of handle (bette…

…r naming)

.changeset/fluffy-files-do.md

@@ -0,0 +1,5 @@
+---
+'@svelte-put/movable': minor
+---
+
+deprecate `trigger` parameter in favor of the more sensible `handle`

packages/actions/movable/src/movable.ts

@@ -31,15 +31,15 @@ declare global {
  * @example
  *
  * A more typical & complex usage of `movable`: move a node
- * when user clicks and on a trigger; and limit the movement within
+ * when user clicks and on a handle; and limit the movement within
  * a certain boundary.
  *
  * ```html
  * <script lang="ts">
  *   import { movable } from '@svelte-put/movable';
  *
  *   let modal = false;
- *   let triggerNode: HTMLElement;
+ *   let handleNode: HTMLElement;
  *   let containerNode: HTMLElement;
  * </script>
  *
@@ -53,12 +53,12 @@ declare global {
  *           delta: '20%',
  *           parent: containerNode,
  *         },
- *         trigger: triggerNode,
+ *         handle: handleNode,
  *       }}
  *       on:movablestart={(event) => console.log('movable:start', event.detail.node, event.detail.position)}
  *       on:movableend={(event) => console.log('movable:end', event.detail.node, event.detail.position)}
  *     >
- *       <button bind:this={triggerNode}>
+ *       <button bind:this={handleNode}>
  *          likely some 'move' icon
  *       </button>
  *
@@ -71,7 +71,7 @@ declare global {
  *
  * Things that will happen in the above example:
  *
- * 1. on `mousedown` of the trigger (`button` element), a `movablestart` {@link https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent | CustomEvent } is dispatched,
+ * 1. on `mousedown` of the handle (`button` element), a `movablestart` {@link https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent | CustomEvent } is dispatched,
  *
  * 2. any `mousemove` event will tell `div` to move accordingly;
  *
@@ -91,8 +91,8 @@ declare global {
  * <Component use:movable/>
  * ```
  *
- * It is recommended to use the `trigger` option in {@link MovableParameters } to avoid unintended behavior.
- * If no `trigger` is provided, the whole node is the trigger and it might be difficult for
+ * It is recommended to use the `handle` option in {@link MovableParameters } to avoid unintended behavior.
+ * If no `handle` is provided, the whole node is the handle and it might be difficult for
  * user to copy texts within the node.
  *
  * Be aware of side effects:
@@ -109,7 +109,7 @@ declare global {
  *
  */
 export function movable(node: HTMLElement, parameters: MovableParameters = { enabled: true }) {
-  let { parent, normalizedDelta, trigger, enabled, ignore } = input(node, parameters);
+  let { parent, normalizedDelta, handle, enabled, ignore } = input(node, parameters);
 
   const lastMousePosition = { x: 0, y: 0 };
   const lastNodePosition = { top: 0, left: 0 };
@@ -228,7 +228,7 @@ export function movable(node: HTMLElement, parameters: MovableParameters = { ena
   const onMouseDown = (event: MouseEvent) => {
     const ignoreSelector = ignore.join(',');
     if (ignoreSelector) {
-      const excludedNodes = Array.from(trigger.querySelectorAll(ignore.join(', ')));
+      const excludedNodes = Array.from(handle.querySelectorAll(ignore.join(', ')));
       if (excludedNodes.some((node) => node.isSameNode(event.target as HTMLElement))) {
         return;
       }
@@ -260,25 +260,25 @@ export function movable(node: HTMLElement, parameters: MovableParameters = { ena
   };
 
   if (enabled) {
-    trigger.addEventListener('mousedown', onMouseDown, true);
+    handle.addEventListener('mousedown', onMouseDown, true);
   }
   return {
     update(parameters: MovableParameters = { enabled: true }) {
       const update = input(node, parameters);
 
-      trigger.removeEventListener('mousedown', onMouseDown, true);
-      update.trigger.addEventListener('mousedown', onMouseDown, true);
+      handle.removeEventListener('mousedown', onMouseDown, true);
+      update.handle.addEventListener('mousedown', onMouseDown, true);
 
       if (!enabled && update.enabled) {
-        trigger.addEventListener('mousedown', onMouseDown, true);
+        handle.addEventListener('mousedown', onMouseDown, true);
       } else if (enabled && !update.enabled) {
-        trigger.removeEventListener('mousedown', onMouseDown, true);
+        handle.removeEventListener('mousedown', onMouseDown, true);
       }
 
-      ({ parent, normalizedDelta, trigger, enabled, ignore } = update);
+      ({ parent, normalizedDelta, handle, enabled, ignore } = update);
     },
     destroy() {
-      trigger.removeEventListener('mousedown', onMouseDown, true);
+      handle.removeEventListener('mousedown', onMouseDown, true);
     },
   };
 }

packages/actions/movable/src/movable.types.ts

@@ -101,26 +101,30 @@ export interface MovableParameters {
   /** Set a limit within which node can be moved */
   limit?: MovableLimit;
   /**
-   * A node that triggers mousedown event, otherwise the node itself is the trigger
+   * A node that triggers mousedown event, otherwise the node itself is the handle
    *
    * @remarks
    *
-   * `trigger` should be an HTMLElement not a Svelte component.
+   * `handle` should be an HTMLElement not a Svelte component.
    *
    * ```html
-   * <div use:movable={{ trigger }}/>
+   * <div use:movable={{ handle }}/>
    *
    * <-- correct usage-->
-   * <div bind:this={trigger} />
+   * <div bind:this={handle} />
    *
    * <-- incorrect usage-->
-   * <Component bind:this={trigger} />
+   * <Component bind:this={handle} />
    * ```
    *
    */
+  handle?: HTMLElement;
+  /**
+   * @deprecated use `handle` instead (same functionality, just more sensible naming)
+   */
   trigger?: HTMLElement;
   /**
-   * CSS selectors within the `trigger` node to exclude from triggering `movable`.
+   * CSS selectors within the `handle` node to exclude from triggering `movable`.
    * Use this options with caution because it might affect performance.
    */
   ignore?: string | string[];

packages/actions/movable/src/utils/input/input.ts

@@ -14,7 +14,7 @@ export function input(node: HTMLElement, parameters: MovableParameters) {
     enabled: parameters.enabled ?? true,
     parent: parameters.limit?.parent,
     normalizedDelta: normalizeDelta(parameters.limit?.delta),
-    trigger: parameters.trigger ?? node,
+    handle: parameters.handle ?? parameters.trigger ?? node,
     ignore: parameters.ignore
       ? typeof parameters.ignore === 'string'
         ? [parameters.ignore]