ng-hub-ui-utils 22.2.0 → 22.3.2

package/types/ng-hub-ui-utils.d.ts

@@ -1,8 +1,352 @@
 import * as i0 from '@angular/core';
-import { NgZone, InjectionToken, EnvironmentProviders, ElementRef, ApplicationRef, TemplateRef, Type, ViewContainerRef, PipeTransform, OnDestroy, ViewRef, ComponentRef, Signal } from '@angular/core';
+import { TemplateRef, NgZone, InjectionToken, EnvironmentProviders, ElementRef, ApplicationRef, Type, ViewContainerRef, PipeTransform, OnDestroy, ViewRef, ComponentRef, Signal } from '@angular/core';
 import * as rxjs from 'rxjs';
 import { Observable, Subscription, Subject, OperatorFunction } from 'rxjs';
 
+/**
+ * Clamps a value into the `[0, max]` range.
+ *
+ * @param value Value to clamp.
+ * @param max Maximum allowed value.
+ * @returns The clamped value.
+ */
+declare function clamp(value: number, max: number): number;
+/**
+ * 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.
+ */
+declare function moveItemInArray<T>(array: T[], fromIndex: number, toIndex: number): void;
+/**
+ * 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.
+ */
+declare function transferArrayItem<T>(source: T[], target: T[], fromIndex: number, toIndex: number): void;
+/**
+ * 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.
+ */
+declare function copyArrayItem<T>(source: ReadonlyArray<T>, target: T[], fromIndex: number, toIndex: number): void;
+/**
+ * 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.
+ */
+declare function computeTargetIndex(targetIndex: number, after: boolean, sameContainer: boolean, fromIndex: number): number;
+/**
+ * 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.
+ */
+declare function toAbsoluteIndex(visibleIndex: number, sliceStart: number): number;
+/**
+ * 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.
+ */
+declare function containsNode(node: any, target: any, childrenKey: string): boolean;
+
+/**
+ * Side a dragged item is dropped relative to a hovered target item.
+ */
+type DropPosition = 'before' | 'after';
+/**
+ * Transport driving a drag gesture: native HTML5 drag-and-drop or the Pointer Events
+ * touch/pen fallback.
+ */
+type DragPointerMode = 'native' | 'pointer';
+/**
+ * Opaque reference to the collection an item belongs to during a drag operation.
+ *
+ * A draggable surface can be a tree of collections (e.g. a list root plus nested children,
+ * or a board's columns each holding cards). A `DragContainerRef` pins the exact collection
+ * (its data array) so reorder/transfer operate on the right place — including cross-instance
+ * transfers where source and target live in different component instances.
+ *
+ * Consumers backed by reactive forms can extend this interface to also carry the mirroring
+ * `FormArray`; the coordinator treats the reference opaquely and never reads extra fields.
+ *
+ * @template T Item type held by the collection.
+ */
+interface DragContainerRef<T = any> {
+    /** Stable key identifying this collection within its owner (used for DOM hit-testing). */
+    key: string;
+    /** Identifier of the owning component instance. */
+    ownerId: string;
+    /** Drag group shared across owners, or `null` when the owner has no group. */
+    group: string | null;
+    /** The data array backing this collection. */
+    items: T[];
+    /** Parent item owning this collection in a nested structure, or `null` for the root. */
+    parentItem: T | null;
+    /** Nesting depth (0 for the root collection). */
+    depth: number;
+    /** Optional discriminator when an owner manages more than one kind of collection. */
+    kind?: string;
+}
+/**
+ * Snapshot of the item currently being dragged and where it came from.
+ *
+ * @template T Item type.
+ */
+interface ActiveDrag<T = any> {
+    /** Identifier of the source owner. */
+    sourceId: string;
+    /** Drag group of the source owner (`null` when ungrouped). */
+    sourceGroup: string | null;
+    /** The item being dragged. */
+    item: T;
+    /** The collection the item was picked from. */
+    sourceContainer: DragContainerRef<T>;
+    /** Absolute index of the item in its source collection. */
+    sourceIndex: number;
+    /** Transport driving the gesture. */
+    pointerMode: DragPointerMode;
+    /** Optional discriminator (e.g. `'card'` vs `'column'`). */
+    kind?: string;
+}
+/**
+ * Transient drop target updated while hovering during a drag.
+ *
+ * @template T Item type.
+ */
+interface DragTarget<T = any> {
+    /** Identifier of the hovered owner. */
+    ownerId: string;
+    /** The collection being hovered. */
+    container: DragContainerRef<T>;
+    /** Absolute index of the hovered item (ignored when `atEnd` is `true`). */
+    index: number;
+    /** Drop side relative to the hovered item. */
+    position: DropPosition;
+    /** Whether the drop lands at the end of the collection. */
+    atEnd: boolean;
+}
+/**
+ * Registration entry an owner publishes so the coordinator can resolve its group lazily,
+ * refresh/commit on its behalf, and resolve a drop target from a DOM point during the
+ * Pointer Events fallback (where hit-testing crosses component instances).
+ */
+interface DragRegistration {
+    /** Identifier of the owner. */
+    ownerId: string;
+    /** Lazily reads the owner's current drag group. */
+    group: () => string | null;
+    /** Re-renders the owner (used after a cross-owner transfer mutates it). */
+    refresh?: () => void;
+    /** Commits the pending drop as the destination owner. */
+    commit?: () => void;
+    /** Resolves a drop target inside this owner from a DOM element and pointer coordinates. */
+    resolveTarget?: (element: HTMLElement, clientX: number, clientY: number) => DragTarget | null;
+}
+
+/**
+ * Minimal rectangle shape (a subset of `DOMRect`) used for drop-position math.
+ */
+interface DropRect {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+    width: number;
+    height: number;
+}
+/**
+ * Layout axis of a draggable collection, used to decide the drop side.
+ *
+ * - `vertical`: rows stacked top-to-bottom (default lists, board cards).
+ * - `horizontal`: items laid left-to-right (board columns).
+ * - `grid`: wrapping grid (list `cards` layout) — vertical band first, then horizontal.
+ */
+type DragAxis = 'vertical' | 'horizontal' | 'grid';
+/**
+ * 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'`.
+ */
+declare function resolveDropPosition(pointerX: number, pointerY: number, rect: DropRect, axis: DragAxis, isRtl: boolean): DropPosition;
+
+/**
+ * A rendered drag image, plus a disposer to tear it down once the drag ends.
+ */
+interface DragImageResult {
+    /** The root element to pass to `dataTransfer.setDragImage`. */
+    node: HTMLElement;
+    /** Destroys the embedded view and removes the rendered nodes. */
+    destroy(): void;
+}
+/**
+ * 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).
+ */
+declare function createNativeDragImage(template: TemplateRef<any>, context: Record<string, unknown>, container?: HTMLElement): DragImageResult | null;
+
+/**
+ * Configuration for a Pointer Events drag session — the touch/pen fallback for native
+ * HTML5 drag-and-drop, used where native dragging is unavailable (mobile/tablet).
+ */
+interface PointerDragSessionConfig {
+    /** The `pointerdown` event that initiated the gesture. */
+    startEvent: PointerEvent;
+    /** The element being dragged. */
+    sourceEl: HTMLElement;
+    /** Builds the floating ghost content (custom preview render or a clone). */
+    ghostFactory: () => HTMLElement;
+    /** Distance in pixels the pointer must travel before a drag begins (default 8). */
+    threshold?: number;
+    /** Called once the gesture passes the threshold and becomes a drag. */
+    onStart: () => void;
+    /** Called on every move while dragging, with viewport coordinates. */
+    onMove: (clientX: number, clientY: number) => void;
+    /** Called on drop (pointer up after a real drag), with viewport coordinates. */
+    onDrop: (clientX: number, clientY: number) => void;
+    /** Called when the gesture is cancelled (e.g. `pointercancel`). */
+    onCancel: () => void;
+    /** Always called last for cleanup, regardless of outcome. */
+    onEnd: () => void;
+}
+/**
+ * Handle to an in-progress Pointer Events drag session.
+ */
+interface PointerDragSession {
+    /** Aborts the session and runs cleanup. */
+    destroy(): void;
+}
+/**
+ * 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.
+ */
+declare function createPointerDragSession(config: PointerDragSessionConfig): PointerDragSession;
+
+/**
+ * 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.
+ */
+declare class HubDragDropService {
+    #private;
+    /** The drag currently in progress, or `null`. */
+    readonly active: i0.Signal<ActiveDrag<any> | null>;
+    /** The current drop target, or `null`. */
+    readonly target: i0.Signal<DragTarget<any> | null>;
+    /** Whether a drag is in progress. */
+    readonly isDragging: i0.Signal<boolean>;
+    /**
+     * Registers an owner so it can participate in (and be a target of) cross-owner transfers.
+     *
+     * @param registration The owner registration.
+     */
+    register(registration: DragRegistration): void;
+    /**
+     * Removes an owner registration (call on destroy).
+     *
+     * @param ownerId Identifier of the owner to remove.
+     */
+    unregister(ownerId: string): void;
+    /**
+     * Starts a drag, recording the active item and clearing any previous target.
+     *
+     * @param drag The active drag snapshot.
+     */
+    begin(drag: ActiveDrag): void;
+    /**
+     * Updates the transient drop target while hovering.
+     *
+     * @param target The hovered target, or `null` to clear it.
+     */
+    setTarget(target: DragTarget | null): void;
+    /**
+     * Ends the current drag and clears all transient state.
+     */
+    end(): void;
+    /**
+     * 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: string): boolean;
+    /**
+     * 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: string): void;
+    /**
+     * 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: string): void;
+    /**
+     * 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: number, clientY: number): DragTarget | null;
+    static ɵfac: i0.ɵɵFactoryDeclaration<HubDragDropService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<HubDragDropService>;
+}
+
 declare const FOCUSABLE_ELEMENTS_SELECTOR: string;
 /**
  * Returns first and last focusable elements inside of a given element based on specific CSS selector
@@ -611,5 +955,5 @@ declare function debouncedSignal<T>(sourceSignal: Signal<T>, debounceDelay?: num
  */
 declare function getActiveElement(root?: Document | ShadowRoot): Element | null;
 
-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 type { ConnectionPosition, HorizontalConnectionPos, HubTooltipPlacement, HubTranslationConfig, OverlayConfig, ScrollbarReverter, TransitionCtx, TransitionEndFn, TransitionOptions, TransitionStartFn, VerticalConnectionPos };
+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 };
+export type { ActiveDrag, ConnectionPosition, DragAxis, DragContainerRef, DragImageResult, DragPointerMode, DragRegistration, DragTarget, DropPosition, DropRect, HorizontalConnectionPos, HubTooltipPlacement, HubTranslationConfig, OverlayConfig, PointerDragSession, PointerDragSessionConfig, ScrollbarReverter, TransitionCtx, TransitionEndFn, TransitionOptions, TransitionStartFn, VerticalConnectionPos };