@bquery/bquery 1.5.0 → 1.7.0

package/src/dnd/sortable.ts

@@ -0,0 +1,307 @@
+/**
+ * Sortable list with animated reordering via pointer events.
+ *
+ * Makes children of a container sortable by dragging. Items are
+ * rearranged in the DOM with optional CSS animation.
+ *
+ * @module bquery/dnd
+ */
+
+import type { SortEventData, SortableHandle, SortableOptions } from './types';
+
+/**
+ * Gets the sortable items within a container.
+ * @internal
+ */
+const getItems = (container: HTMLElement, selector: string): HTMLElement[] => {
+  return Array.from(container.querySelectorAll(selector)) as HTMLElement[];
+};
+
+/**
+ * Finds the closest sortable item to a given Y (or X) position.
+ * @internal
+ */
+const getClosestItem = (
+  items: HTMLElement[],
+  clientPos: number,
+  axis: 'x' | 'y',
+  dragged: HTMLElement
+): { element: HTMLElement; index: number } | null => {
+  let closest: { element: HTMLElement; index: number; distance: number } | null = null;
+
+  for (let i = 0; i < items.length; i++) {
+    const item = items[i];
+    if (item === dragged) continue;
+
+    const rect = item.getBoundingClientRect();
+    const mid = axis === 'y' ? rect.top + rect.height / 2 : rect.left + rect.width / 2;
+    const distance = clientPos - mid;
+
+    if (
+      closest === null ||
+      (distance < 0 && distance > closest.distance) ||
+      (closest.distance >= 0 && distance < 0 && Math.abs(distance) < Math.abs(closest.distance))
+    ) {
+      // Find the item we're just before
+      if (distance < 0) {
+        closest = { element: item, index: i, distance };
+      }
+    }
+  }
+
+  return closest ? { element: closest.element, index: closest.index } : null;
+};
+
+/**
+ * Makes the children of a container sortable by dragging.
+ *
+ * Features:
+ * - Pointer event based (touch + mouse)
+ * - Animated reordering with configurable duration
+ * - Axis constraint (vertical or horizontal)
+ * - Optional drag handle
+ * - Placeholder element during sort
+ * - Callbacks: `onSortStart`, `onSortMove`, `onSortEnd`
+ *
+ * @param container - The container element whose children will be sortable
+ * @param options - Configuration options
+ * @returns A handle with `destroy()`, `disable()`, and `enable()` methods
+ *
+ * @example
+ * ```ts
+ * import { sortable } from '@bquery/bquery/dnd';
+ *
+ * const handle = sortable(document.querySelector('#list'), {
+ *   items: 'li',
+ *   axis: 'y',
+ *   animationDuration: 200,
+ *   onSortEnd: ({ oldIndex, newIndex }) => {
+ *     console.log(`Moved from ${oldIndex} to ${newIndex}`);
+ *   },
+ * });
+ *
+ * // Later:
+ * handle.destroy();
+ * ```
+ */
+export const sortable = (container: HTMLElement, options: SortableOptions = {}): SortableHandle => {
+  const {
+    items: itemSelector = ':scope > *',
+    axis = 'y',
+    handle,
+    placeholderClass = 'bq-sort-placeholder',
+    sortingClass = 'bq-sorting',
+    animationDuration = 200,
+    onSortStart,
+    onSortMove,
+    onSortEnd,
+  } = options;
+
+  let enabled = !options.disabled;
+  let isDragging = false;
+  let dragItem: HTMLElement | null = null;
+  let placeholder: HTMLElement | null = null;
+  let startIndex = -1;
+  let startPointerY = 0;
+  let startPointerX = 0;
+  let itemStartTop = 0;
+  let itemStartLeft = 0;
+
+  const createEventData = (item: HTMLElement, oldIdx: number, newIdx: number): SortEventData => ({
+    container,
+    item,
+    oldIndex: oldIdx,
+    newIndex: newIdx,
+  });
+
+  const onPointerDown = (e: PointerEvent): void => {
+    if (!enabled) return;
+
+    const target = e.target as HTMLElement;
+
+    // Find the item being dragged
+    const items = getItems(container, itemSelector);
+    let item: HTMLElement | null = null;
+
+    for (const it of items) {
+      if (it.contains(target)) {
+        item = it;
+        break;
+      }
+    }
+
+    if (!item) return;
+
+    // Check handle constraint
+    if (handle && !target.closest(handle)) return;
+
+    e.preventDefault();
+
+    isDragging = true;
+    dragItem = item;
+    startIndex = items.indexOf(item);
+    startPointerY = e.clientY;
+    startPointerX = e.clientX;
+
+    const rect = item.getBoundingClientRect();
+    itemStartTop = rect.top;
+    itemStartLeft = rect.left;
+
+    // Create placeholder
+    placeholder = document.createElement('div');
+    placeholder.classList.add(placeholderClass);
+    placeholder.style.width = `${rect.width}px`;
+    placeholder.style.height = `${rect.height}px`;
+    placeholder.style.boxSizing = 'border-box';
+
+    // Style the dragged item
+    item.classList.add(sortingClass);
+    item.style.position = 'fixed';
+    item.style.width = `${rect.width}px`;
+    item.style.height = `${rect.height}px`;
+    item.style.left = `${rect.left}px`;
+    item.style.top = `${rect.top}px`;
+    item.style.zIndex = '999999';
+    item.style.pointerEvents = 'none';
+    item.style.margin = '0';
+
+    // Insert placeholder where the item was
+    item.parentNode?.insertBefore(placeholder, item);
+
+    container.setPointerCapture(e.pointerId);
+
+    onSortStart?.(createEventData(item, startIndex, startIndex));
+  };
+
+  const onPointerMove = (e: PointerEvent): void => {
+    if (!isDragging || !dragItem || !placeholder) return;
+
+    e.preventDefault();
+
+    const deltaX = e.clientX - startPointerX;
+    const deltaY = e.clientY - startPointerY;
+
+    // Move the dragged item
+    if (axis === 'y') {
+      dragItem.style.top = `${itemStartTop + deltaY}px`;
+    } else {
+      dragItem.style.left = `${itemStartLeft + deltaX}px`;
+    }
+
+    // Find the closest item to determine insertion point
+    const items = getItems(container, itemSelector);
+    const clientPos = axis === 'y' ? e.clientY : e.clientX;
+    const closest = getClosestItem(items, clientPos, axis, dragItem);
+
+    if (closest) {
+      // Move placeholder before the closest element
+      container.insertBefore(placeholder, closest.element);
+    } else {
+      // Append to end
+      container.appendChild(placeholder);
+    }
+
+    const currentIndex = Array.from(container.children).indexOf(placeholder);
+    onSortMove?.(createEventData(dragItem, startIndex, currentIndex));
+  };
+
+  const onPointerUp = (e: PointerEvent): void => {
+    if (!isDragging || !dragItem || !placeholder) return;
+
+    isDragging = false;
+    const draggedItem = dragItem;
+
+    // Get final index
+    const newIndex = Array.from(container.children).indexOf(placeholder);
+
+    // Animate the item back to the placeholder position
+    const placeholderRect = placeholder.getBoundingClientRect();
+    const itemRect = draggedItem.getBoundingClientRect();
+
+    if (animationDuration > 0) {
+      const deltaX = placeholderRect.left - itemRect.left;
+      const deltaY = placeholderRect.top - itemRect.top;
+
+      draggedItem.style.transition = `transform ${animationDuration}ms ease`;
+      draggedItem.style.transform = `translate(${deltaX}px, ${deltaY}px)`;
+
+      let finalized = false;
+      let timeoutId: number | null = null;
+      const finalize = (): void => {
+        if (finalized) return;
+        finalized = true;
+        if (timeoutId !== null) {
+          window.clearTimeout(timeoutId);
+          timeoutId = null;
+        }
+        resetDragItem();
+        onSortEnd?.(createEventData(draggedItem, startIndex, newIndex));
+      };
+      timeoutId = window.setTimeout(() => {
+        finalize();
+      }, animationDuration + 50);
+
+      draggedItem.addEventListener('transitionend', finalize, { once: true });
+    } else {
+      resetDragItem();
+      onSortEnd?.(createEventData(draggedItem, startIndex, newIndex));
+    }
+
+    container.releasePointerCapture(e.pointerId);
+  };
+
+  const resetDragItem = (): void => {
+    if (!dragItem || !placeholder) return;
+
+    // Insert the real item where the placeholder is
+    placeholder.parentNode?.insertBefore(dragItem, placeholder);
+    placeholder.remove();
+    placeholder = null;
+
+    // Reset styles
+    dragItem.classList.remove(sortingClass);
+    dragItem.style.position = '';
+    dragItem.style.width = '';
+    dragItem.style.height = '';
+    dragItem.style.left = '';
+    dragItem.style.top = '';
+    dragItem.style.zIndex = '';
+    dragItem.style.pointerEvents = '';
+    dragItem.style.margin = '';
+    dragItem.style.transition = '';
+    dragItem.style.transform = '';
+
+    dragItem = null;
+  };
+
+  container.addEventListener('pointerdown', onPointerDown);
+  container.addEventListener('pointermove', onPointerMove);
+  container.addEventListener('pointerup', onPointerUp);
+  container.addEventListener('pointercancel', onPointerUp);
+
+  // Prevent default touch behavior on container
+  container.style.touchAction = 'none';
+
+  return {
+    destroy: () => {
+      container.removeEventListener('pointerdown', onPointerDown);
+      container.removeEventListener('pointermove', onPointerMove);
+      container.removeEventListener('pointerup', onPointerUp);
+      container.removeEventListener('pointercancel', onPointerUp);
+      container.style.touchAction = '';
+
+      if (isDragging) {
+        resetDragItem();
+      }
+    },
+    disable: () => {
+      enabled = false;
+    },
+    enable: () => {
+      enabled = true;
+    },
+    get enabled() {
+      return enabled;
+    },
+  };
+};

package/src/dnd/types.ts

@@ -0,0 +1,293 @@
+/**
+ * Type definitions for the bQuery Drag & Drop module.
+ *
+ * @module bquery/dnd
+ */
+
+// ─── Shared Types ────────────────────────────────────────────────────────────
+
+/**
+ * Axis constraint for draggable elements.
+ * - `'x'` — horizontal only
+ * - `'y'` — vertical only
+ * - `'both'` — free movement (default)
+ */
+export type DragAxis = 'x' | 'y' | 'both';
+
+/**
+ * Position coordinates in pixels.
+ */
+export interface DragPosition {
+  /** Horizontal position in pixels. */
+  x: number;
+  /** Vertical position in pixels. */
+  y: number;
+}
+
+/**
+ * A bounding rectangle used to constrain drag movement.
+ */
+export interface BoundsRect {
+  /** Minimum X coordinate (left edge). */
+  left: number;
+  /** Minimum Y coordinate (top edge). */
+  top: number;
+  /** Maximum X coordinate (right edge). */
+  right: number;
+  /** Maximum Y coordinate (bottom edge). */
+  bottom: number;
+}
+
+/**
+ * Bounds constraint for draggable elements.
+ * - `'parent'` — constrain to parent element's bounds
+ * - A CSS selector string — constrain to the matched element's bounds
+ * - A `BoundsRect` — constrain to explicit coordinates
+ */
+export type DragBounds = 'parent' | string | BoundsRect;
+
+/**
+ * Data passed to all drag event callbacks.
+ */
+export interface DragEventData {
+  /** The dragged element. */
+  element: HTMLElement;
+  /** Current position relative to the initial position (0,0 at start). */
+  position: DragPosition;
+  /** Movement delta since the last event. */
+  delta: DragPosition;
+  /** The original pointer event. */
+  event: PointerEvent;
+}
+
+// ─── Draggable ───────────────────────────────────────────────────────────────
+
+/**
+ * Configuration options for `draggable()`.
+ */
+export interface DraggableOptions {
+  /**
+   * Axis constraint for movement.
+   * @default 'both'
+   */
+  axis?: DragAxis;
+
+  /**
+   * Bounds constraint. Restricts the element's movement to within the
+   * specified area.
+   */
+  bounds?: DragBounds;
+
+  /**
+   * CSS selector for a drag handle. If provided, only pointer events
+   * on matching child elements will initiate a drag.
+   */
+  handle?: string;
+
+  /**
+   * Whether to show a ghost/clone preview during drag instead of
+   * moving the original element. The ghost follows the pointer while
+   * the original stays in place.
+   * @default false
+   */
+  ghost?: boolean;
+
+  /**
+   * CSS class applied to the ghost element.
+   * @default 'bq-drag-ghost'
+   */
+  ghostClass?: string;
+
+  /**
+   * CSS class applied to the element while it is being dragged.
+   * @default 'bq-dragging'
+   */
+  draggingClass?: string;
+
+  /**
+   * Whether the element is initially disabled for dragging.
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * Called when a drag operation starts.
+   */
+  onDragStart?: (data: DragEventData) => void;
+
+  /**
+   * Called continuously during drag movement.
+   */
+  onDrag?: (data: DragEventData) => void;
+
+  /**
+   * Called when a drag operation ends.
+   */
+  onDragEnd?: (data: DragEventData) => void;
+}
+
+/**
+ * Handle returned by `draggable()` for controlling the drag behavior.
+ */
+export interface DraggableHandle {
+  /** Remove all event listeners and clean up. */
+  destroy: () => void;
+  /** Disable dragging. */
+  disable: () => void;
+  /** Re-enable dragging. */
+  enable: () => void;
+  /** Whether dragging is currently enabled. */
+  readonly enabled: boolean;
+}
+
+// ─── Droppable ───────────────────────────────────────────────────────────────
+
+/**
+ * Data passed to droppable event callbacks.
+ */
+export interface DropEventData {
+  /** The drop zone element. */
+  zone: HTMLElement;
+  /** The dragged element entering/leaving/dropping onto the zone. */
+  dragged: HTMLElement;
+  /** The original pointer event. */
+  event: PointerEvent;
+}
+
+/**
+ * Configuration options for `droppable()`.
+ */
+export interface DroppableOptions {
+  /**
+   * CSS class applied to the zone while a draggable element is over it.
+   * @default 'bq-drop-over'
+   */
+  overClass?: string;
+
+  /**
+   * CSS selector or predicate to filter which dragged elements are
+   * accepted. If a string, only elements matching the selector can
+   * be dropped. If a function, return `true` to accept.
+   */
+  accept?: string | ((el: HTMLElement) => boolean);
+
+  /**
+   * Called when a dragged element enters the drop zone.
+   */
+  onDragEnter?: (data: DropEventData) => void;
+
+  /**
+   * Called while a dragged element is over the drop zone.
+   */
+  onDragOver?: (data: DropEventData) => void;
+
+  /**
+   * Called when a dragged element leaves the drop zone.
+   */
+  onDragLeave?: (data: DropEventData) => void;
+
+  /**
+   * Called when a dragged element is dropped onto the zone.
+   */
+  onDrop?: (data: DropEventData) => void;
+}
+
+/**
+ * Handle returned by `droppable()` for controlling the drop zone.
+ */
+export interface DroppableHandle {
+  /** Remove all event listeners and clean up. */
+  destroy: () => void;
+}
+
+// ─── Sortable ────────────────────────────────────────────────────────────────
+
+/**
+ * Data passed to sortable event callbacks.
+ */
+export interface SortEventData {
+  /** The container element. */
+  container: HTMLElement;
+  /** The item being moved. */
+  item: HTMLElement;
+  /** The old index before the move. */
+  oldIndex: number;
+  /** The new index after the move. */
+  newIndex: number;
+}
+
+/**
+ * Configuration options for `sortable()`.
+ */
+export interface SortableOptions {
+  /**
+   * CSS selector for the sortable items within the container.
+   * @default '> *'
+   */
+  items?: string;
+
+  /**
+   * Axis constraint for sorting.
+   * @default 'y'
+   */
+  axis?: 'x' | 'y';
+
+  /**
+   * CSS selector for a drag handle within each item. If provided,
+   * only pointer events on handle elements initiate sorting.
+   */
+  handle?: string;
+
+  /**
+   * CSS class applied to the placeholder element during sorting.
+   * @default 'bq-sort-placeholder'
+   */
+  placeholderClass?: string;
+
+  /**
+   * CSS class applied to the item being sorted.
+   * @default 'bq-sorting'
+   */
+  sortingClass?: string;
+
+  /**
+   * Duration of the reorder animation in milliseconds.
+   * @default 200
+   */
+  animationDuration?: number;
+
+  /**
+   * Whether sorting is initially disabled.
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * Called when sorting starts.
+   */
+  onSortStart?: (data: SortEventData) => void;
+
+  /**
+   * Called when an item is moved to a new position.
+   */
+  onSortMove?: (data: SortEventData) => void;
+
+  /**
+   * Called when sorting ends and the item is placed.
+   */
+  onSortEnd?: (data: SortEventData) => void;
+}
+
+/**
+ * Handle returned by `sortable()` for controlling the sortable list.
+ */
+export interface SortableHandle {
+  /** Remove all event listeners and clean up. */
+  destroy: () => void;
+  /** Disable sorting. */
+  disable: () => void;
+  /** Re-enable sorting. */
+  enable: () => void;
+  /** Whether sorting is currently enabled. */
+  readonly enabled: boolean;
+}