samuelcharpentier / dragtoblank

Draggable class built with TypeScript for front end use. Meant to be extended and used as dependencies.

Table of Contents

1. Introduction
2. Installation
3. Usage
4. API
5. Packages extending DragToBlank
6. License

DragToBlank

DragToBlank is a simple, lightweight TypeScript NPM library that provides a foundation for adding drag interactions to your web applications. By extending the DragToBlank class and overriding the mouseDown, dragStart, dragMove, and dragEnd methods, you can easily customize the behavior of your DragToBlank elements.

Installation

npm install -D drag-to-blank

Usage

First, import the DragToBlank class from the package:

import { DragToBlank } from 'drag-to-blank';

Next, extend the DragToBlank class and override or add the necessary methods and properties:

export class MyDragToBlank extends DragToBlank {
	//...custom class properties
	protected override defaultClassName = 'my-DragToBlank';
	private options?: MyDragToBlankOptions;

	//... custom constructor
	constructor(
		element: HTMLElement,
		options?: MyDragToBlankOptions,
	) {
		super(element);
		this.options = options;
	}

	protected mouseDown(event: MouseEvent): void {
		// Custom mouse down behavior
	}

	protected dragStart(event: MouseEvent): void {
		// Custom drag start behavior
	}

	protected dragMove(event: MouseEvent): void {
		// Custom drag move behavior
	}

	protected dragEnd(event: MouseEvent): void {
		// Custom drag end behavior
	}

	//...custom class methods
}

Finally, instantiate your DragToBlank element by passing in the element to be dragged or by using the apply method to apply the DragToBlank behavior to all elements with the specified class name (defaults to DragToBlank if not overridden) or a specified class name:

import { MyDragToBlank } from 'my-DragToBlank';

const DragToBlank = new MyDragToBlank(
	document.getElementById('my-DragToBlank-element'),
);
// or
MyDragToBlank.apply();
// or
MyDragToBlank.apply('my-DragToBlank-class');

API

Mouse Data

To access mouse data, use the mouseData property of the DragToBlank class. Its get() method retrieves the mouse data for a given mouse data type. If no data is found for the key, it returns undefined. The keys are as follows:

• 'mouseDown'
• 'dragStart'
• 'dragMove'
• 'dragEnd'

const mouseDownData = this.mouseData.get('mouseDown');

All mouse data is stored as an object of type StampedPosition which has the following properties:

Property	Type	Description
timestamp	number	The timestamp of the mouse event.
position	{x : number, y : number}	The position of the mouse event.

The mouse data of dragMove is stored as a LinkedStampedPosition object. It extends the StampedPosition type. Its additional properties are:

Property	Type	Description
prev	StampedPosition	The previous mouse move StampedPosition. On initializing the first node, the value of dragStart is assigned to prev.
next	StampedPosition	The next mouse move StampedPosition. On the latest node, this is undefined.

Static Properties

Property	Type	Access	Description
defaultClassName	string	protected static	The default class name to use when applying DragToBlank behavior to elements (defaults to DragToBlank)
instances	DragToBlank[]	static	An array to hold all instances of the DragToBlank class

Methods

Method	Description
apply(className?: string)	Applies DragToBlank behavior to all elements with either the specified className if provided or the defaultClassName property value
mouseDown(event: MouseEvent)	This method is called when the mouse button is pressed down on the DragToBlank element. Override this method to implement custom behavior if desired.
dragStart(event: MouseEvent)	This method is called a single time on the first mouse movement event following the mouseDown() method. Override this method to implement custom behavior if desired.
dragMove(event: MouseEvent)	This method is called on every mouse movement event after the dragStart() method. Override this method to implement custom behavior if desired.
dragEnd(event: MouseEvent)	This method is called when the mouse button is released after the dragStart() method. Override this method to implement custom behavior if desired.

Example

This example shows how to extend the DragToBlank class to implement custom behavior. In this example, we will log a message, the original event and the mouse down data to the console on each mouse move event that occurs after the mouse is down event occured on the target element.

import { DragToBlank } from 'DragToBlank';

export class MyDragToBlank extends DragToBlank {
	protected override defaultClassName = 'my-DragToBlank';

	constructor(element: HTMLElement) {
		super(element);
	}

	protected override dragMove(event: MouseEvent): void {
		let mouseDownData = this.mouseData.get('mouseDown');
		console.log('my mouse move', event, mouseDownData);
	}
}

Packages extending DragToBlank

This section includes links to packages that extend the DragToBlank base class. If you've created a package that extends DragToBlank, feel free to add it here.

1. DragToScroll: Allows you to drag with the mouse to scroll a page or any elements with scrollbars.
2. DragToTranslate: Allows you to drag with the mouse to translate an element.

To add your extension to this list, please submit a pull request with the changes to this README file.

License

MIT