tiny-essentials
Version:
Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.
392 lines • 14.7 kB
text/typescript
export default TinyDragger;
export type VibrationPatterns = {
/**
* - Pattern to vibrate on start
*/
start: number[] | false;
/**
* - Pattern to vibrate on end
*/
end: number[] | false;
/**
* - Pattern to vibrate on collision
*/
collide: number[] | false;
/**
* - Pattern to vibrate while moving
*/
move: number[] | false;
};
/**
* @typedef {Object} VibrationPatterns
* @property {number[]|false} start - Pattern to vibrate on start
* @property {number[]|false} end - Pattern to vibrate on end
* @property {number[]|false} collide - Pattern to vibrate on collision
* @property {number[]|false} move - Pattern to vibrate while moving
*/
/**
* TinyDragger enables drag-and-drop functionality for a DOM element.
* It supports jail boundaries, optional collision detection, vibration feedback,
* automatic reverting, proxy dragging, and event dispatching.
*/
declare class TinyDragger {
static Utils: {
TinyHtml: typeof TinyHtml;
getElsRelativeCenterOffset(rect1: ObjRect, rect2: ObjRect): {
x: number;
y: number;
};
getElsCollDirDepth(rect1: ObjRect, rect2: ObjRect): {
inDir: Dirs | null;
dirX: Dirs | null;
dirY: Dirs | null;
depthX: number;
depthY: number;
};
getElsCollDetails(rect1: ObjRect, rect2: ObjRect): {
depth: CollData;
dirs: CollDirs;
isNeg: NegCollDirs;
};
areElsCollTop: (rect1: ObjRect, rect2: ObjRect) => boolean;
areElsCollBottom: (rect1: ObjRect, rect2: ObjRect) => boolean;
areElsCollLeft: (rect1: ObjRect, rect2: ObjRect) => boolean;
areElsCollRight: (rect1: ObjRect, rect2: ObjRect) => boolean;
areElsCollPerfTop: (rect1: ObjRect, rect2: ObjRect) => boolean;
areElsCollPerfBottom: (rect1: ObjRect, rect2: ObjRect) => boolean;
areElsCollPerfLeft: (rect1: ObjRect, rect2: ObjRect) => boolean;
areElsCollPerfRight: (rect1: ObjRect, rect2: ObjRect) => boolean;
areElsColliding: (rect1: ObjRect, rect2: ObjRect) => boolean;
areElsPerfColliding: (rect1: ObjRect, rect2: ObjRect) => boolean;
getElsColliding: (rect1: ObjRect, rect2: ObjRect) => string | null;
getElsPerfColliding: (rect1: ObjRect, rect2: ObjRect) => "top" | "bottom" | "left" | "right" | null;
getElsCollOverlap: (rect1: ObjRect, rect2: ObjRect) => {
overlapLeft: number;
overlapRight: number;
overlapTop: number;
overlapBottom: number;
};
getElsCollOverlapPos: ({ overlapLeft, overlapRight, overlapTop, overlapBottom, }?: {
overlapLeft?: number | undefined;
overlapRight?: number | undefined;
overlapTop?: number | undefined;
overlapBottom?: number | undefined;
}) => {
dirX: Dirs;
dirY: Dirs;
};
getRectCenter: (rect: ObjRect) => {
x: number;
y: number;
};
};
/** @typedef {(event: TouchEvent) => void} TouchDragEvent */
/**
* @param {HTMLElement|TinyHtml<any>} targetElement - The element to make draggable.
* @param {Object} [options={}] - Configuration options.
* @param {HTMLElement} [options.jail] - Optional container to restrict dragging within.
* @param {boolean} [options.mirrorElem=true] - Use a visual clone instead of dragging the original element.
* @param {number} [options.defaultZIndex] - Sets the z-index value applied when dragging starts.
* @param {boolean} [options.collisionByMouse=false] - Use mouse position for collision instead of element rect.
* @param {string} [options.classDragging='dragging'] - CSS class applied to the clone during dragging.
* @param {string} [options.classBodyDragging='drag-active'] - CSS class applied to <body> during dragging.
* @param {string} [options.classJailDragging='jail-drag-active'] - CSS class applied to jail element during drag.
* @param {string} [options.classJailDragDisabled='jail-drag-disabled'] - CSS class applied to jail element disabled.
* @param {string} [options.classDragCollision='dragging-collision'] - CSS class applied to collision element.
* @param {boolean} [options.lockInsideJail=false] - Restrict movement within the jail container.
* @param {boolean} [options.dropInJailOnly=false] - Restrict drop within the jail container.
* @param {boolean} [options.multiCollision=false] - Enables returning multiple collided elements.
* @param {VibrationPatterns|false} [options.vibration=false] - Vibration feedback configuration.
* @param {boolean} [options.revertOnDrop=false] - Whether to return to original position on drop.
* @param {string} [options.classHidden='drag-hidden'] - CSS class to hide original element during dragging.
* @throws {Error} If any option has an invalid type.
*/
constructor(targetElement: HTMLElement | TinyHtml<any>, options?: {
jail?: HTMLElement | undefined;
mirrorElem?: boolean | undefined;
defaultZIndex?: number | undefined;
collisionByMouse?: boolean | undefined;
classDragging?: string | undefined;
classBodyDragging?: string | undefined;
classJailDragging?: string | undefined;
classJailDragDisabled?: string | undefined;
classDragCollision?: string | undefined;
lockInsideJail?: boolean | undefined;
dropInJailOnly?: boolean | undefined;
multiCollision?: boolean | undefined;
vibration?: false | VibrationPatterns | undefined;
revertOnDrop?: boolean | undefined;
classHidden?: string | undefined;
});
/** @private */
private _onMouseDown;
/** @private */
private _onMouseMove;
/** @private */
private _onMouseUp;
/**
* @type {TouchDragEvent}
* @private
*/
private _onTouchStart;
/**
* @type {TouchDragEvent}
* @private
*/
private _onTouchMove;
/**
* @type {TouchDragEvent}
* @private
*/
private _onTouchEnd;
/**
* Enables the drag functionality.
*/
enable(): void;
/**
* Disables the drag functionality.
*/
disable(): void;
/**
* Adds an element to be considered for collision detection.
* @param {HTMLElement} element - The element to track collisions with.
* @throws {Error} If the element is not a valid HTMLElement.
*/
addCollidable(element: HTMLElement): void;
/**
* Removes a collidable element from the tracking list.
* @param {HTMLElement} element - The element to remove.
* @throws {Error} If the element is not a valid HTMLElement.
*/
removeCollidable(element: HTMLElement): void;
/**
* Sets vibration patterns for drag events.
* @param {Object} [param0={}] - Vibration pattern configuration.
* @param {number[]|false} [param0.startPattern=false] - Vibration on drag start.
* @param {number[]|false} [param0.endPattern=false] - Vibration on drag end.
* @param {number[]|false} [param0.collidePattern=false] - Vibration on collision.
* @param {number[]|false} [param0.movePattern=false] - Vibration during movement.
* @throws {Error} If any pattern is not false or an array of numbers.
*/
setVibrationPattern({ startPattern, endPattern, collidePattern, movePattern, }?: {
startPattern?: false | number[] | undefined;
endPattern?: false | number[] | undefined;
collidePattern?: false | number[] | undefined;
movePattern?: false | number[] | undefined;
}): void;
/**
* Disables all vibration feedback.
*/
disableVibration(): void;
/**
* Calculates the cursor offset relative to the top-left of the target element.
* @param {MouseEvent|Touch} event - The mouse or touch event.
* @returns {{x: number, y: number}} The offset in pixels.
* @throws {Error} If event is not a MouseEvent or Touch with clientX/clientY.
*/
getOffset(event: MouseEvent | Touch): {
x: number;
y: number;
};
/**
* Handles dragging collision.
* @param {MouseEvent|Touch} event - The drag event.
*/
checkDragCollision(event: MouseEvent | Touch): void;
/**
* Handles the collision of a drag.
* @param {MouseEvent|Touch} event - The release event.
* @returns {{ inJail: boolean; collidedElements: (HTMLElement | null)[] }}
*/
execCollision(event: MouseEvent | Touch): {
inJail: boolean;
collidedElements: (HTMLElement | null)[];
};
/**
* Returns all elements currently colliding with the given rectangle.
*
* @param {DOMRect} rect - Bounding rectangle of the dragged proxy.
* @returns {HTMLElement[]} A list of all collided elements.
* @throws {Error} If the input is not a valid DOMRect with numeric bounds.
*/
getAllCollidedElementsByRect(rect: DOMRect): HTMLElement[];
/**
* Detects collision based on rectangle intersection.
* @param {DOMRect} rect - Bounding rectangle of the dragged proxy.
* @returns {HTMLElement|null} The collided element or null.
* @throws {Error} If rect is not a DOMRect with valid numeric properties.
*/
getCollidedElementByRect(rect: DOMRect): HTMLElement | null;
/**
* @param {number} x - Horizontal screen coordinate.
* @param {number} y - Vertical screen coordinate.
* @returns {HTMLElement[]} The collided element or null.
*/
getAllCollidedElements(x: number, y: number): HTMLElement[];
/**
* Detects collision with a point using element bounding rectangles.
* @param {number} x - Horizontal screen coordinate.
* @param {number} y - Vertical screen coordinate.
* @returns {HTMLElement|null} The collided element or null.
*/
getCollidedElement(x: number, y: number): HTMLElement | null;
/**
* Gets whether dragging is currently active.
* @returns {boolean}
*/
getDragging(): boolean;
/**
* Gets whether movement is restricted inside the jail container.
* @returns {boolean}
*/
getLockInsideJail(): boolean;
/**
* Sets whether movement is restricted inside the jail container.
* @param {boolean} value
*/
setLockInsideJail(value: boolean): void;
/**
* Gets whether the element should revert to original position on drop.
* @returns {boolean}
*/
getRevertOnDrop(): boolean;
/**
* Sets whether the element should revert to original position on drop.
* @param {boolean} value
*/
setRevertOnDrop(value: boolean): void;
/**
* Gets whether collision detection uses mouse position.
* @returns {boolean}
*/
getCollisionByMouse(): boolean;
/**
* Sets whether collision detection uses mouse position.
* @param {boolean} value
*/
setCollisionByMouse(value: boolean): void;
/**
* Gets whether dropping is restricted inside the jail container.
* @returns {boolean}
*/
getDropInJailOnly(): boolean;
/**
* Sets whether dropping is restricted inside the jail container.
* @param {boolean} value
*/
setDropInJailOnly(value: boolean): void;
/**
* Returns the current default z-index used for draggable items.
* @returns {number}
*/
getDefaultZIndex(): number;
/**
* Sets a new default z-index for draggable items.
* @param {number} newZIndex
*/
setDefaultZIndex(newZIndex: number): void;
/**
* Returns whether the draggable element is mirrored or the original.
* @returns {boolean}
*/
isMirrorEnabled(): boolean;
/**
* Sets whether the draggable element should be a mirror or the original.
* @param {boolean} useMirror
*/
setMirrorEnabled(useMirror: boolean): void;
/**
* Returns the original target element being dragged.
* @returns {HTMLElement}
*/
getTarget(): HTMLElement;
/**
* Returns the current jail container (if any).
* @returns {HTMLElement|null}
*/
getJail(): HTMLElement | null;
/**
* Returns the current proxy element being dragged (if any).
* @returns {HTMLElement|null}
*/
getDragProxy(): HTMLElement | null;
/**
* Returns the last collided element (if any).
* @returns {HTMLElement|null}
*/
getLastCollision(): HTMLElement | null;
/**
* Returns all registered collidable elements.
* @returns {HTMLElement[]}
*/
getCollidables(): HTMLElement[];
/**
* Returns the CSS class used to hide the target during drag.
* @returns {string}
*/
getDragHiddenClass(): string;
/**
* Returns the CSS class applied to the clone during dragging.
* @returns {string}
*/
getClassDragging(): string;
/**
* Returns the CSS class applied to <body> during dragging.
* @returns {string}
*/
getClassBodyDragging(): string;
/**
* Returns the CSS class applied to the jail during dragging.
* @returns {string}
*/
getClassJailDragging(): string;
/**
* Returns the CSS class applied to the jail when dragging is disabled.
* @returns {string}
*/
getClassJailDragDisabled(): string;
/**
* Returns the CSS class applied to a collided element.
* @returns {string}
*/
getClassDragCollision(): string;
/**
* Returns the full vibration configuration.
* @returns {VibrationPatterns}
*/
getVibrations(): VibrationPatterns;
/**
* Returns the vibration pattern for drag start.
* @returns {number[]|boolean}
*/
getStartVibration(): number[] | boolean;
/**
* Returns the vibration pattern for drag end.
* @returns {number[]|boolean}
*/
getEndVibration(): number[] | boolean;
/**
* Returns the vibration pattern for collisions.
* @returns {number[]|boolean}
*/
getCollideVibration(): number[] | boolean;
/**
* Returns the vibration pattern during movement.
* @returns {number[]|boolean}
*/
getMoveVibration(): number[] | boolean;
/**
* Returns whether the dragger is currently enabled.
* @returns {boolean}
*/
isEnabled(): boolean;
/**
* Completely disables drag-and-drop and cleans up all event listeners.
* Does NOT remove the original HTML element.
*/
destroy(): void;
#private;
}
import TinyHtml from './TinyHtml.mjs';
import * as TinyCollision from '../basics/collision.mjs';
//# sourceMappingURL=TinyDragger.d.mts.map