ng-hub-ui-utils 22.2.0 → 22.3.2

package/fesm2022/ng-hub-ui-utils.mjs

@@ -1,9 +1,553 @@
+import * as i0 from '@angular/core';
+import { signal, computed, Injectable, effect, InjectionToken, inject, makeEnvironmentProviders, ElementRef, TemplateRef, createComponent, ApplicationRef, Pipe, ChangeDetectorRef, Injector, ViewContainerRef, NgZone, input, Renderer2, RendererStyleFlags2, HostListener, Directive } from '@angular/core';
 import { fromEvent, Observable, Subject, isObservable, EMPTY, of, timer, race } from 'rxjs';
 import { takeUntil, map, filter, withLatestFrom, endWith, take, mergeMap, tap } from 'rxjs/operators';
-import * as i0 from '@angular/core';
-import { signal, effect, InjectionToken, inject, Injectable, makeEnvironmentProviders, ElementRef, TemplateRef, createComponent, ApplicationRef, Pipe, ChangeDetectorRef, Injector, ViewContainerRef, NgZone, input, Renderer2, RendererStyleFlags2, HostListener, Directive } from '@angular/core';
 import { DOCUMENT } from '@angular/common';
 
+/**
+ * Clamps a value into the `[0, max]` range.
+ *
+ * @param value Value to clamp.
+ * @param max Maximum allowed value.
+ * @returns The clamped value.
+ */
+function clamp(value, max) {
+    return Math.max(0, Math.min(max, value));
+}
+/**
+ * Moves an item within an array in place (mirrors `@angular/cdk`'s `moveItemInArray`).
+ *
+ * @param array Array to mutate.
+ * @param fromIndex Current index of the item.
+ * @param toIndex Target index of the item.
+ */
+function moveItemInArray(array, fromIndex, toIndex) {
+    const from = clamp(fromIndex, array.length - 1);
+    const to = clamp(toIndex, array.length - 1);
+    if (from === to) {
+        return;
+    }
+    const target = array[from];
+    const delta = to < from ? -1 : 1;
+    for (let i = from; i !== to; i += delta) {
+        array[i] = array[i + delta];
+    }
+    array[to] = target;
+}
+/**
+ * Transfers an item from one array to another in place (mirrors `transferArrayItem`).
+ *
+ * @param source Source array.
+ * @param target Target array.
+ * @param fromIndex Index of the item in the source array.
+ * @param toIndex Insertion index in the target array.
+ */
+function transferArrayItem(source, target, fromIndex, toIndex) {
+    const from = clamp(fromIndex, source.length - 1);
+    const to = clamp(toIndex, target.length);
+    if (source.length) {
+        target.splice(to, 0, source.splice(from, 1)[0]);
+    }
+}
+/**
+ * Copies an item from one array into another in place, leaving the source untouched.
+ *
+ * @param source Source array.
+ * @param target Target array.
+ * @param fromIndex Index of the item in the source array.
+ * @param toIndex Insertion index in the target array.
+ */
+function copyArrayItem(source, target, fromIndex, toIndex) {
+    if (!source.length) {
+        return;
+    }
+    const from = clamp(fromIndex, source.length - 1);
+    const to = clamp(toIndex, target.length);
+    target.splice(to, 0, source[from]);
+}
+/**
+ * Computes the destination index in the underlying collection from the hovered target index
+ * and the drop side. When reordering within the same container, the index is adjusted to
+ * account for the gap left by removing the dragged item.
+ *
+ * @param targetIndex Absolute index of the hovered target item.
+ * @param after Whether the item is dropped after (vs before) the target.
+ * @param sameContainer Whether source and target collections are the same.
+ * @param fromIndex Absolute index the dragged item occupied in the source collection.
+ * @returns The resolved destination index.
+ */
+function computeTargetIndex(targetIndex, after, sameContainer, fromIndex) {
+    let index = after ? targetIndex + 1 : targetIndex;
+    if (sameContainer && fromIndex < index) {
+        index -= 1;
+    }
+    return Math.max(0, index);
+}
+/**
+ * Maps a paginated visible index to its absolute index in the underlying collection.
+ *
+ * @param visibleIndex Index within the currently rendered slice.
+ * @param sliceStart Absolute index of the first item in the slice.
+ * @returns The absolute index.
+ */
+function toAbsoluteIndex(visibleIndex, sliceStart) {
+    return sliceStart + visibleIndex;
+}
+/**
+ * Determines whether `target` is `node` or any of its descendants in a tree, where children
+ * are stored under the `childrenKey` property. Used to forbid dropping a node into its own
+ * subtree (which would create a cycle).
+ *
+ * @param node Root node of the subtree to search.
+ * @param target Item to look for (e.g. the parent of a candidate drop container).
+ * @param childrenKey Property name holding the children collection.
+ * @returns `true` when `target` is `node` or one of its descendants.
+ */
+function containsNode(node, target, childrenKey) {
+    if (target == null) {
+        return false;
+    }
+    if (node === target) {
+        return true;
+    }
+    const children = node?.[childrenKey];
+    if (!Array.isArray(children)) {
+        return false;
+    }
+    return children.some((child) => containsNode(child, target, childrenKey));
+}
+
+/**
+ * Resolves whether a dragged item should drop before or after the hovered target, based on
+ * the pointer position relative to the target's bounding rectangle and the layout axis.
+ *
+ * For `vertical` the Y axis decides; for `horizontal` the X axis decides (mirrored in RTL);
+ * for `grid` the vertical band decides across rows and the horizontal axis decides within
+ * the same row (mirrored in RTL).
+ *
+ * @param pointerX Pointer X in viewport coordinates.
+ * @param pointerY Pointer Y in viewport coordinates.
+ * @param rect Bounding rectangle of the target item.
+ * @param axis Layout axis of the collection.
+ * @param isRtl Whether the collection is in right-to-left mode.
+ * @returns `'before'` or `'after'`.
+ */
+function resolveDropPosition(pointerX, pointerY, rect, axis, isRtl) {
+    if (axis === 'horizontal') {
+        const midX = rect.left + rect.width / 2;
+        const before = isRtl ? pointerX > midX : pointerX < midX;
+        return before ? 'before' : 'after';
+    }
+    const midY = rect.top + rect.height / 2;
+    if (axis === 'vertical') {
+        return pointerY < midY ? 'before' : 'after';
+    }
+    // grid
+    if (pointerY < rect.top) {
+        return 'before';
+    }
+    if (pointerY > rect.bottom) {
+        return 'after';
+    }
+    const midX = rect.left + rect.width / 2;
+    const before = isRtl ? pointerX > midX : pointerX < midX;
+    return before ? 'before' : 'after';
+}
+
+/**
+ * Renders a template off-screen so it can be used as a native drag image
+ * (`dataTransfer.setDragImage`). The caller is responsible for calling `setDragImage` and,
+ * on `dragend`, the returned `destroy()`.
+ *
+ * @param template Template to render as the drag preview.
+ * @param context Template context (e.g. `{ item }`).
+ * @param container Optional host element to mount into; when omitted, an off-screen holder is
+ *   appended to `document.body`.
+ * @returns The rendered image and its disposer, or `null` when nothing renders (e.g. SSR or
+ *   an empty template).
+ */
+function createNativeDragImage(template, context, container) {
+    if (typeof document === 'undefined') {
+        return null;
+    }
+    const view = template.createEmbeddedView(context);
+    view.detectChanges();
+    const node = view.rootNodes.find((candidate) => candidate.nodeType === Node.ELEMENT_NODE);
+    if (!node) {
+        view.destroy();
+        return null;
+    }
+    const mountedNodes = [...view.rootNodes];
+    let holder = null;
+    if (container) {
+        mountedNodes.forEach((rootNode) => container.appendChild(rootNode));
+    }
+    else {
+        holder = document.createElement('div');
+        holder.style.position = 'fixed';
+        holder.style.top = '-9999px';
+        holder.style.left = '-9999px';
+        holder.style.pointerEvents = 'none';
+        mountedNodes.forEach((rootNode) => holder.appendChild(rootNode));
+        document.body.appendChild(holder);
+    }
+    return {
+        node,
+        destroy: () => {
+            // Angular's `EmbeddedViewRef.destroy()` tears down the view but does NOT remove the
+            // DOM nodes it produced, so remove them explicitly to keep the helper self-contained
+            // (no caller-side `innerHTML` clearing needed). The off-screen holder is removed whole.
+            view.destroy();
+            if (holder) {
+                holder.remove();
+            }
+            else {
+                mountedNodes.forEach((rootNode) => rootNode.remove?.());
+            }
+        }
+    };
+}
+
+const EDGE_MARGIN = 48;
+const MAX_SCROLL_SPEED = 16;
+/**
+ * Creates a Pointer Events drag session that mirrors native drag-and-drop on touch devices.
+ *
+ * The session waits for the pointer to pass a movement threshold (so taps still behave as
+ * taps), then renders a floating ghost that follows the finger, reports hover positions via
+ * `onMove`, autoscrolls when near a scroll container's edges, and commits on pointer up.
+ *
+ * @param config Session configuration.
+ * @returns A handle whose `destroy()` aborts the session.
+ */
+function createPointerDragSession(config) {
+    const threshold = config.threshold ?? 8;
+    const pointerId = config.startEvent.pointerId;
+    const startX = config.startEvent.clientX;
+    const startY = config.startEvent.clientY;
+    const rect = config.sourceEl.getBoundingClientRect();
+    const grabOffsetX = startX - rect.left;
+    const grabOffsetY = startY - rect.top;
+    let started = false;
+    let ghost = null;
+    let scrollContainer = window;
+    let rafId = null;
+    let scrollVelocity = 0;
+    /**
+     * Positions the ghost under the pointer.
+     *
+     * @param x Pointer X.
+     * @param y Pointer Y.
+     */
+    const positionGhost = (x, y) => {
+        if (ghost) {
+            ghost.style.transform = `translate(${x - grabOffsetX}px, ${y - grabOffsetY}px)`;
+        }
+    };
+    /**
+     * Runs the autoscroll animation loop while the pointer sits in an edge zone.
+     */
+    const scrollStep = () => {
+        if (scrollVelocity !== 0) {
+            if (scrollContainer === window) {
+                window.scrollBy(0, scrollVelocity);
+            }
+            else {
+                scrollContainer.scrollTop += scrollVelocity;
+            }
+            rafId = requestAnimationFrame(scrollStep);
+        }
+        else {
+            rafId = null;
+        }
+    };
+    /**
+     * Updates the autoscroll velocity from the pointer's proximity to the container edges.
+     *
+     * @param y Pointer Y.
+     */
+    const updateAutoscroll = (y) => {
+        const bounds = scrollContainer === window
+            ? { top: 0, bottom: window.innerHeight }
+            : scrollContainer.getBoundingClientRect();
+        if (y < bounds.top + EDGE_MARGIN) {
+            scrollVelocity = -Math.ceil((MAX_SCROLL_SPEED * (bounds.top + EDGE_MARGIN - y)) / EDGE_MARGIN);
+        }
+        else if (y > bounds.bottom - EDGE_MARGIN) {
+            scrollVelocity = Math.ceil((MAX_SCROLL_SPEED * (y - (bounds.bottom - EDGE_MARGIN))) / EDGE_MARGIN);
+        }
+        else {
+            scrollVelocity = 0;
+        }
+        if (scrollVelocity !== 0 && rafId === null) {
+            rafId = requestAnimationFrame(scrollStep);
+        }
+    };
+    /**
+     * Begins the actual drag once the threshold is exceeded.
+     *
+     * @param x Pointer X.
+     * @param y Pointer Y.
+     */
+    const beginDrag = (x, y) => {
+        started = true;
+        scrollContainer = findScrollContainer(config.sourceEl);
+        ghost = config.ghostFactory();
+        ghost.classList.add('hub-drag-ghost');
+        ghost.style.position = 'fixed';
+        ghost.style.top = '0';
+        ghost.style.left = '0';
+        ghost.style.width = `${rect.width}px`;
+        ghost.style.pointerEvents = 'none';
+        ghost.style.zIndex = '2147483647';
+        ghost.style.margin = '0';
+        positionGhost(x, y);
+        document.body.appendChild(ghost);
+        config.onStart();
+    };
+    /**
+     * Handles pointer movement: starts the drag past threshold, then tracks and autoscrolls.
+     *
+     * @param event Pointer move event.
+     */
+    const onPointerMove = (event) => {
+        if (event.pointerId !== pointerId) {
+            return;
+        }
+        const { clientX, clientY } = event;
+        if (!started) {
+            if (Math.abs(clientX - startX) < threshold && Math.abs(clientY - startY) < threshold) {
+                return;
+            }
+            beginDrag(clientX, clientY);
+        }
+        event.preventDefault();
+        positionGhost(clientX, clientY);
+        config.onMove(clientX, clientY);
+        updateAutoscroll(clientY);
+    };
+    /**
+     * Handles pointer up: commits the drop when a drag actually happened.
+     *
+     * @param event Pointer up event.
+     */
+    const onPointerUp = (event) => {
+        if (event.pointerId !== pointerId) {
+            return;
+        }
+        if (started) {
+            config.onDrop(event.clientX, event.clientY);
+        }
+        cleanup();
+    };
+    /**
+     * Handles pointer cancellation.
+     *
+     * @param event Pointer cancel event.
+     */
+    const onPointerCancel = (event) => {
+        if (event.pointerId !== pointerId) {
+            return;
+        }
+        if (started) {
+            config.onCancel();
+        }
+        cleanup();
+    };
+    /**
+     * Removes listeners, the ghost and any pending animation frame, then notifies the owner.
+     */
+    const cleanup = () => {
+        window.removeEventListener('pointermove', onPointerMove);
+        window.removeEventListener('pointerup', onPointerUp);
+        window.removeEventListener('pointercancel', onPointerCancel);
+        if (rafId !== null) {
+            cancelAnimationFrame(rafId);
+            rafId = null;
+        }
+        scrollVelocity = 0;
+        ghost?.remove();
+        ghost = null;
+        try {
+            config.sourceEl.releasePointerCapture(pointerId);
+        }
+        catch {
+            // Pointer capture may not be held; ignore.
+        }
+        config.onEnd();
+    };
+    try {
+        config.sourceEl.setPointerCapture(pointerId);
+    }
+    catch {
+        // Environments without pointer capture (e.g. tests) can still proceed.
+    }
+    window.addEventListener('pointermove', onPointerMove, { passive: false });
+    window.addEventListener('pointerup', onPointerUp);
+    window.addEventListener('pointercancel', onPointerCancel);
+    return { destroy: cleanup };
+}
+/**
+ * Finds the nearest vertically scrollable ancestor of an element, falling back to `window`.
+ *
+ * @param el Starting element.
+ * @returns The scroll container (an element) or `window`.
+ */
+function findScrollContainer(el) {
+    let node = el?.parentElement ?? null;
+    while (node && node !== document.body && node !== document.documentElement) {
+        const style = getComputedStyle(node);
+        const overflowY = style.overflowY;
+        if ((overflowY === 'auto' || overflowY === 'scroll') && node.scrollHeight > node.clientHeight) {
+            return node;
+        }
+        node = node.parentElement;
+    }
+    return window;
+}
+
+/**
+ * Singleton coordinator that backs native HTML5 drag-and-drop reordering and cross-instance
+ * transfers (e.g. between two lists, or any two owners that share a drag group).
+ *
+ * A drag spans two component instances (source and target) and the native `dataTransfer`
+ * payload is unreadable during `dragover`, so a shared, root-provided service is the only
+ * reliable channel to know what is being dragged and from where while hovering. The service
+ * only coordinates state; it never mutates the underlying collections.
+ */
+class HubDragDropService {
+    #registrations = new Map();
+    #active = signal(null, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "#active" }] : /* istanbul ignore next */ []));
+    #target = signal(null, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "#target" }] : /* istanbul ignore next */ []));
+    /** The drag currently in progress, or `null`. */
+    active = this.#active.asReadonly();
+    /** The current drop target, or `null`. */
+    target = this.#target.asReadonly();
+    /** Whether a drag is in progress. */
+    isDragging = computed(() => this.#active() !== null, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "isDragging" }] : /* istanbul ignore next */ []));
+    /**
+     * Registers an owner so it can participate in (and be a target of) cross-owner transfers.
+     *
+     * @param registration The owner registration.
+     */
+    register(registration) {
+        this.#registrations.set(registration.ownerId, registration);
+    }
+    /**
+     * Removes an owner registration (call on destroy).
+     *
+     * @param ownerId Identifier of the owner to remove.
+     */
+    unregister(ownerId) {
+        this.#registrations.delete(ownerId);
+    }
+    /**
+     * Starts a drag, recording the active item and clearing any previous target.
+     *
+     * @param drag The active drag snapshot.
+     */
+    begin(drag) {
+        this.#active.set(drag);
+        this.#target.set(null);
+    }
+    /**
+     * Updates the transient drop target while hovering.
+     *
+     * @param target The hovered target, or `null` to clear it.
+     */
+    setTarget(target) {
+        this.#target.set(target);
+    }
+    /**
+     * Ends the current drag and clears all transient state.
+     */
+    end() {
+        this.#active.set(null);
+        this.#target.set(null);
+    }
+    /**
+     * Determines whether the active drag may be dropped on the given owner. An owner always
+     * accepts its own items (in-owner reorder); a different owner accepts only when both
+     * share the same non-null drag group.
+     *
+     * @param targetOwnerId Identifier of the candidate target owner.
+     * @returns `true` when the drop is allowed.
+     */
+    canDrop(targetOwnerId) {
+        const active = this.#active();
+        if (!active) {
+            return false;
+        }
+        if (targetOwnerId === active.sourceId) {
+            return true;
+        }
+        const registration = this.#registrations.get(targetOwnerId);
+        if (!registration) {
+            return false;
+        }
+        const targetGroup = registration.group();
+        return active.sourceGroup != null && targetGroup != null && active.sourceGroup === targetGroup;
+    }
+    /**
+     * Re-renders an owner on demand (used by the destination owner to refresh the source owner
+     * after a cross-owner transfer).
+     *
+     * @param ownerId Identifier of the owner to refresh.
+     */
+    refreshSource(ownerId) {
+        this.#registrations.get(ownerId)?.refresh?.();
+    }
+    /**
+     * Asks an owner to commit the pending drop as the destination (Pointer Events fallback,
+     * where the source component drives the gesture but the destination must commit/emit).
+     *
+     * @param ownerId Identifier of the destination owner.
+     */
+    requestCommit(ownerId) {
+        this.#registrations.get(ownerId)?.commit?.();
+    }
+    /**
+     * Resolves the drop target under a viewport point by hit-testing the DOM and delegating to
+     * the owning component (which knows its own collections). Used by the Pointer Events
+     * fallback, including cross-owner hovers where the target is a different component.
+     *
+     * @param clientX Viewport X coordinate.
+     * @param clientY Viewport Y coordinate.
+     * @returns The resolved target, or `null` when the point is not over a droppable owner.
+     */
+    resolveTargetAt(clientX, clientY) {
+        if (typeof document === 'undefined') {
+            return null;
+        }
+        const element = document.elementFromPoint(clientX, clientY);
+        const hostEl = element?.closest('[data-hub-drag-owner]');
+        const ownerId = hostEl?.getAttribute('data-hub-drag-owner');
+        if (!element || !ownerId || !this.canDrop(ownerId)) {
+            return null;
+        }
+        return this.#registrations.get(ownerId)?.resolveTarget?.(element, clientX, clientY) ?? null;
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.1", ngImport: i0, type: HubDragDropService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "22.0.1", ngImport: i0, type: HubDragDropService, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.1", ngImport: i0, type: HubDragDropService, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+
+/**
+ * Native HTML5 drag-and-drop core shared across ng-hub-ui libraries.
+ *
+ * Provides the engine-agnostic, reusable pieces of a native drag-and-drop implementation:
+ * pure array helpers, drop-position geometry, drag-image rendering, a Pointer Events touch
+ * fallback, a singleton coordinator service (cross-instance transfers) and shared types.
+ * UI primitives (handle/placeholder/preview directives) stay per-library, since their
+ * selectors and data models differ.
+ */
+
 const FOCUSABLE_ELEMENTS_SELECTOR = [
     'a[href]',
     'button:not([disabled])',
@@ -1463,5 +2007,5 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.1", ngImpor
  * Generated bundle index. Do not edit.
  */
 
-export { ContentRef, FOCUSABLE_ELEMENTS_SELECTOR, GetPipe, HUB_TRANSLATION_CONFIG, HubTranslationService, IsObjectPipe, IsObservablePipe, IsStringPipe, OverlayPosition, OverlayRef, OverlayService, PopupService, ScrollBar, TooltipDirective, TranslatePipe, UcfirstPipe, UnwrapAsyncPipe, closest, debouncedSignal, equals, generateUniqueId, getActiveElement, getFocusableBoundaryElements, getValue, getValueInRange, hubCompleteTransition, hubFocusTrap, hubRunTransition, interpolateString, isDefined, isInteger, isNumber, isObject, isPromise, isString, mergeDeep, padNumber, provideHubTranslation, reflow, regExpEscape, removeAccents, runInZone, toInteger, toString };
+export { ContentRef, FOCUSABLE_ELEMENTS_SELECTOR, GetPipe, HUB_TRANSLATION_CONFIG, HubDragDropService, HubTranslationService, IsObjectPipe, IsObservablePipe, IsStringPipe, OverlayPosition, OverlayRef, OverlayService, PopupService, ScrollBar, TooltipDirective, TranslatePipe, UcfirstPipe, UnwrapAsyncPipe, clamp, closest, computeTargetIndex, containsNode, copyArrayItem, createNativeDragImage, createPointerDragSession, debouncedSignal, equals, generateUniqueId, getActiveElement, getFocusableBoundaryElements, getValue, getValueInRange, hubCompleteTransition, hubFocusTrap, hubRunTransition, interpolateString, isDefined, isInteger, isNumber, isObject, isPromise, isString, mergeDeep, moveItemInArray, padNumber, provideHubTranslation, reflow, regExpEscape, removeAccents, resolveDropPosition, runInZone, toAbsoluteIndex, toInteger, toString, transferArrayItem };
 //# sourceMappingURL=ng-hub-ui-utils.mjs.map