@foblex/drag-toolkit v1.1.0

Foblex Drag Toolkit

A TypeScript library providing foundational classes and utilities for implementing drag-and-drop functionality in Angular applications, with support for both mouse and touch events, and designed to work with or without Angular’s NgZone (zoneless applications). Used in Foblex Flow for drag-and-drop operations.

Overview

Foblex Drag Toolkit simplifies the implementation of drag-and-drop interactions in Angular applications by providing:

• Unified Pointer Events: Abstract classes for handling mouse and touch events uniformly.
• Drag-and-Drop Base Class: An abstract base class DragAndDropBase encapsulating common logic for drag-and-drop operations.
• Event Utilities: Helper functions and classes for event handling, including support for passive event listeners.
• Angular Zone Compatibility: Designed to work with or without Angular’s NgZone, making it suitable for zoneless applications.

By extending the DragAndDropBase class and implementing its abstract methods, developers can create custom drag-and-drop components with consistent behavior across different input types.

Installation

Install the library via npm:

  npm install @foblex/drag-toolkit

Usage

Creating a Custom Drag-and-Drop Component

Extend the DragAndDropBase class and implement the abstract methods:

import { Component, ElementRef } from '@angular/core';
import {
  DragAndDropBase,
  IPointerEvent,
  ICanRunOutsideAngular,
} from '@foblex/drag-toolkit';

@Component({
  selector: 'app-draggable',
  template: `<div #draggableElement>Drag Me!</div>`,
})
export class DraggableComponent extends DragAndDropBase {
  public hostElement: HTMLElement;
  public disabled = false;

  constructor(
    private elementRef: ElementRef,
    ngZone: ICanRunOutsideAngular
  ) {
    super(ngZone);
    this.hostElement = this.elementRef.nativeElement;
  }

  protected prepareDragSequence(event: IPointerEvent): void {
    // Initialize drag operation
  }

  protected finalizeDragSequence(): void {
    // Clean up after drag operation
  }

  protected onSelect(event: Event): void {
    // Handle text selection during drag
    event.preventDefault();
  }

  public onPointerDown(event: IPointerEvent): boolean {
    // Determine if drag should start
    return true;
  }

  public onPointerMove(event: IPointerEvent): void {
    // Handle dragging movement
  }

  public onPointerUp(event: IPointerEvent): void {
    // Handle drag completion
  }
}

Subscribing to Events

Ensure that you call subscribe and unsubscribe methods appropriately, typically in ngOnInit and ngOnDestroy:

import { AfterViewInit, OnDestroy } from '@angular/core';

export class DraggableComponent
  extends DragAndDropBase
  implements AfterViewInit, OnDestroy
{
  // ... (other code)

  ngAfterViewInit(): void {
    this.subscribe(document);
  }

  ngOnDestroy(): void {
    this.unsubscribe();
  }
}

Error Handling

• Synthetic Events: The library checks for synthetic mouse events triggered after touch events to prevent duplicate actions.
• Screen Reader Compatibility: Functions like isFakeMousedownFromScreenReader and isFakeTouchstartFromScreenReader are used to ignore events from screen readers, enhancing accessibility.

License

This project is licensed under the MIT License.

By using the Foblex Drag Toolkit, you can simplify the implementation of complex drag-and-drop interactions in your Angular applications, ensuring consistent behavior across different devices and input types.