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.
123 lines • 4.93 kB
text/typescript
export default TinyDragDropDetector;
export type DragAndDropOptions = {
/**
* - The DOM element where drag listeners will be attached. Defaults to `document.body` if `fullscreen` is true or no target is provided.
*/
target?: HTMLElement | undefined;
/**
* - If true, listeners are attached to the entire page (`document.body`). If false, the `target` must be specified.
*/
fullscreen?: boolean | undefined;
/**
* - CSS class applied to the target element while files are being dragged over it.
*/
hoverClass?: string | undefined;
/**
* - Callback function executed when files are dropped onto the target.
*/
onDrop?: ((files: FileList, event: DragEvent) => void) | undefined;
/**
* - Optional callback triggered when dragging enters the target area.
*/
onEnter?: ((event: DragEvent) => void) | undefined;
/**
* - Optional callback triggered when dragging leaves the target area.
*/
onLeave?: ((event: DragEvent) => void) | undefined;
};
/**
* @typedef {Object} DragAndDropOptions
* @property {HTMLElement} [target=document.body] - The DOM element where drag listeners will be attached. Defaults to `document.body` if `fullscreen` is true or no target is provided.
* @property {boolean} [fullscreen=true] - If true, listeners are attached to the entire page (`document.body`). If false, the `target` must be specified.
* @property {string} [hoverClass="dnd-hover"] - CSS class applied to the target element while files are being dragged over it.
* @property {(files: FileList, event: DragEvent) => void} [onDrop] - Callback function executed when files are dropped onto the target.
* @property {(event: DragEvent) => void} [onEnter] - Optional callback triggered when dragging enters the target area.
* @property {(event: DragEvent) => void} [onLeave] - Optional callback triggered when dragging leaves the target area.
*/
/**
* TinyDragDropDetector
*
* A lightweight utility to detect drag-and-drop file operations on a specific DOM element or the entire page.
* It handles the drag lifecycle (enter, over, leave, drop) and provides hooks for developers to handle file uploads or UI changes.
*
* @class
*/
declare class TinyDragDropDetector {
/**
* Creates a new instance of TinyDragDropDetector to handle drag-and-drop file detection.
*
* @param {DragAndDropOptions} [options={}] - Configuration options for the detector.
* @throws {TypeError} If `target` is not an HTMLElement.
* @throws {TypeError} If `fullscreen` is not a boolean.
* @throws {TypeError} If `hoverClass` is not a string.
* @throws {TypeError} If `onDrop` is defined but not a function.
* @throws {TypeError} If `onEnter` is defined but not a function.
* @throws {TypeError} If `onLeave` is defined but not a function.
*/
constructor(options?: DragAndDropOptions);
/**
* Handles the `dragenter` event.
* Adds the hover CSS class and triggers the `onEnter` callback if provided.
* @private
* @param {DragEvent} event - The dragenter event.
* @returns {void}
*/
private _handleDragEnter;
/**
* Handles the `dragover` event.
* Prevents default to allow drop and sets the drop effect.
* @private
* @param {DragEvent} event - The dragover event.
* @returns {void}
*/
private _handleDragOver;
/**
* Handles the `dragleave` event.
* Removes the hover class and triggers the `onLeave` callback if provided.
* @private
* @param {DragEvent} event - The dragleave event.
* @returns {void}
*/
private _handleDragLeave;
/**
* Handles the `drop` event.
* Removes the hover class, resets dragging state, and triggers the `onDrop` callback.
* @private
* @param {DragEvent} event - The drop event.
* @returns {void}
*/
private _handleDrop;
/**
* Returns the current target DOM element where the listeners are attached.
* @returns {HTMLElement}
*/
getTarget(): HTMLElement;
/**
* Returns the CSS class applied during drag hover.
* @returns {string}
*/
getHoverClass(): string;
/**
* Indicates whether the detector is operating in fullscreen mode.
* @returns {boolean}
*/
isFullScreen(): boolean;
/**
* Returns whether a drag operation is currently active over the target.
* @returns {boolean}
*/
isDragging(): boolean;
/**
* Returns whether the event listeners are currently bound to the target.
* @returns {boolean}
*/
bound(): boolean;
/**
* Destroys the detector instance, unbinding all event listeners and cleaning up.
* Should be called when the detector is no longer needed to avoid memory leaks.
* @returns {void}
*/
destroy(): void;
#private;
}
//# sourceMappingURL=TinyDragDropDetector.d.mts.map