@dflex/utils/types/index.d.ts

Utility package for DFlex

declare class AxesPoint<T = number> {
    x: T;
    y: T;
    constructor(x: T, y: T);
}

declare class Point<T> extends AxesPoint<T> {
    /**
     * Assigns the given values to the local instance.
     *
     * @param x
     * @param y
     */
    setAxes(x: T, y: T): void;
    /**
     * Clone a given point into local instance.
     *
     * @param target
     */
    clone(target: Point<T> | AxesPoint<T>): void;
    /**
     * Get local instance of point.
     *
     * @returns
     */
    getInstance(): AxesPoint<T>;
    /**
     *  True when both axes match the same value.
     *
     * @param target
     * @returns
     */
    isInstanceEqual(target: Point<T> | AxesPoint<T>): boolean;
    /**
     * True when both axes match the same value.
     *
     * @param x
     * @param y
     * @returns
     */
    isEqual(x: T, y: T): boolean;
    /**
     * True when both axes doesn't match the given value.
     *
     * @param x
     * @param y
     * @returns
     */
    isNotEqual(x: T, y: T): boolean;
}

/** Four direction instance - clockwise */
declare class AbstractBox<T = number> {
    /** Minimal `Y` coordinate */
    top: T;
    /** Maximal `X` coordinate */
    right: T;
    /** Maximal `Y` coordinate */
    bottom: T;
    /** Minimal `X` coordinate */
    left: T;
    /**
     *
     * @param top - minimal y coordinate
     * @param right - maximal x coordinate
     * @param bottom - maximal y coordinate
     * @param left - minimal x coordinate
     */
    constructor(top: T, right: T, bottom: T, left: T);
}

interface Dimensions {
    height: number;
    width: number;
}
type Direction = 1 | -1;
/** Single Axis. */
type Axis = "x" | "y";
/** Bi-directional Axis. */
type Axes = Axis | "z";
declare const BOTH_AXIS: readonly Axis[];
type CubicBezier = "ease" | "ease-in" | "ease-out" | "ease-in-out" | "linear";
type AnimationOpts = {
    /**
     * The easing function to use for the animation.
     * Specifies the speed curve of the animation.
     * Example values: 'linear', 'ease-in', 'ease-out', 'ease-in-out'.
     * (Default: 'ease-in')
     */
    easing: CubicBezier;
    /**
     * The duration of the animation in milliseconds.
     * Specifies how long the animation should take to complete.
     * (Default: 'dynamic')
     */
    duration: number | "dynamic";
} | null;
type CSSStyle = Record<string, string | null>;
type CSSClass = string;
type CSS = CSSClass | CSSStyle;

/** Four direction instance - clockwise */
declare class Box<T> extends AbstractBox<T> {
    clone(box: AbstractBox<T>): void;
    /**
     * Set all directions.
     *
     * @param top
     * @param right
     * @param bottom
     * @param left
     */
    setBox(top: T, right: T, bottom: T, left: T): this;
    /**
     * Get an instance of FourDirections.
     *
     * @returns
     */
    getBox(): AbstractBox<T>;
    /**
     * Set one axis only.
     *
     * @param axis
     * @param x
     * @param y
     */
    setByAxis(axis: Axis, x: T, y: T): void;
    /**
     * Set one direction only.
     *
     * @param axis
     * @param direction
     * @param value
     */
    setOne(axis: Axis, direction: Direction, value: T): void;
    /**
     * Get the value of one direction.
     *
     * @param axis
     * @param direction
     * @returns
     */
    getOne(axis: Axis, direction: Direction): T;
    setPositionInstance(point: AxesPoint<T>): void;
    setPosition(x: T, y: T): void;
    hasEqualPosition(x: T, y: T): boolean;
    /**
     * Get starting point instance.
     *
     * @returns
     */
    getPosition(): AxesPoint<T>;
}

declare class BoxBool extends Box<boolean> {
    constructor(top: boolean, right: boolean, bottom: boolean, left: boolean);
    /**
     * Reset all directions to false.
     *
     * @returns
     */
    setFalsy(): this;
    /**
     * True when one of two directions in a given axis is true.
     *
     * @param axis
     * @returns
     */
    isTruthyByAxis(axis: Axis): boolean;
    isTruthyOnSide(axis: Axis, direction: Direction): boolean;
    /**
     * True when one of four directions is true.
     *
     * @returns
     */
    isTruthy(): boolean;
}

declare class BoxNum extends Box<number> {
    private _isUnder;
    private _isAbove;
    private _isOnLeft;
    private _isOneRight;
    private _isAboveThresholdTop;
    private _isRightOfThresholdRight;
    private _isBelowThresholdBottom;
    private _isLeftOfThresholdLeft;
    private _isBelowOrEqualThresholdTop;
    private _isLeftOrEqualThresholdRight;
    private _isAboveOrEqualThresholdBottom;
    private _isRightOrEqualThresholdLeft;
    isBoxIntersect(box: AbstractBox): boolean;
    isOutThreshold(threshold: AbstractBox, preservedBoxResult: BoxBool, axis: Axis | null): boolean;
    isInsideThreshold(threshold: AbstractBox): boolean;
    getSurroundingBox(box: AbstractBox): AbstractBox;
    isPositionedY(box: AbstractBox): boolean;
    assignBiggestBox(box: AbstractBox): void;
}

type AbstractBoxRect = AbstractBox & Dimensions;
declare class BoxRect extends BoxNum {
    width: number;
    height: number;
    /**
     * clockwise
     *
     * @param top
     * @param right
     * @param bottom
     * @param left
     */
    constructor(top: number, right: number, bottom: number, left: number);
    /**
     *
     * @param top
     * @param left
     * @param height
     * @param width
     * @returns
     */
    setByPointAndDimensions(top: number, left: number, height: number, width: number): void;
    /**
     * Update the box point position.
     *
     * @param x
     * @param y
     * @returns
     */
    setAxes(x: number, y: number): void;
    getInstance(): AbstractBoxRect;
    getViewportPos(viewportTop: number, viewportLeft: number, asBoxNum: true): BoxNum;
    getViewportPos(viewportTop: number, viewportLeft: number, asBoxNum: false): AbstractBox & Dimensions;
    /**
     * Gets the width/height difference between two boxes based on axis.
     *
     * @param axis
     * @param box
     * @returns
     */
    getDimensionDiff(axis: Axis, box: AbstractBoxRect): number;
    /**
     * Gets the  left/top difference between two points based on axis.
     *
     * @param axis
     * @param point
     * @returns
     */
    getPositionDiff(axis: Axis, point: AxesPoint): number;
}

declare class PointNum extends Point<number> {
    /**
     * Increase the current point by the given another point.
     *
     * @param point
     */
    increase(point: AxesPoint): this;
    composeBox(box: AbstractBox, isInner: boolean): BoxNum;
    onSameAxis(axis: Axis, point: AxesPoint): boolean;
}

declare class PointBool extends Point<boolean> {
    /**
     * True when both points X and Y are true.
     * @returns
     */
    isOneTruthy(): boolean;
    /**
     * True when one point is false.
     * @returns
     */
    isAllFalsy(): boolean;
    /**
     * Set both x and y to false.
     */
    setFalsy(): void;
}

interface ThresholdPercentages {
    /** vertical threshold in percentage from 0-100 */
    vertical: number;
    /** horizontal threshold in percentage from 0-100 */
    horizontal: number;
}
declare class DFlexThreshold {
    readonly thresholds: Record<string, BoxNum>;
    private _pixels;
    private _percentages;
    isOut: Record<string, BoxBool>;
    static containerKey(depth: number, SK: string): string;
    static depthKey(depth: number): string;
    constructor(percentages: ThresholdPercentages);
    private _createPixels;
    /** Assign threshold property and create new instance for is out indicators */
    private _createThreshold;
    /**
     * Set the main threshold for the element based on the element's dimensions
     * and threshold types. For dragged and containers threshold type is outer
     * `isInner=false` and for the rest of the elements `isInner=true.`
     * Note: Duplicate threshold keys will throw an error.
     *
     * @param key
     * @param box
     * @param isInner
     */
    setMainThreshold(key: string, box: AbstractBoxRect, isInner: boolean): void;
    /**
     * Update existing threshold with new dimensions.
     *
     * @param key
     * @param rect
     * @param isInner
     */
    updateMainThreshold(key: string, rect: AbstractBox, isInner: boolean): void;
    getElmMainThreshold(rect: AbstractBox): BoxNum;
    /**
     * Assign outer threshold for the container. Along with another threshold
     * called insertion threshold which defines the area where the element can be
     * inserted during the migration taking into consideration the biggest hight
     * and width for the depth by using `unifiedContainerDimensions`. And create
     * accumulated depth threshold.
     *
     * @param SK
     * @param depth
     * @param containerRect
     * @param unifiedContainerDimensions
     */
    setContainerThreshold(SK: string, depth: number, containerRect: AbstractBox, unifiedContainerDimensions: Dimensions): void;
    isOutThreshold(key: string, box: BoxNum, axis: Axis | null): boolean;
    destroy(): void;
}

type MovementDirection = "r" | "l" | "d" | "u";
/**
 * Represents a threshold dead zone used to manage the stabilizing zone that prevents
 * the dragged element from getting stuck between two intersected thresholds.
 */
declare class ThresholdDeadZone {
    /**
     * A bounding box representing the threshold dead zone.
     */
    private _area;
    /**
     * Indicates movement directions for each axis (x and y).
     */
    private _movement;
    constructor();
    /**
     * Sets up the stabilizing zone to prevent the dragged element from getting stuck
     * between two intersected thresholds.
     *
     * @param axis - The axis (x or y) along which the stabilizing zone is applied.
     * @param movementDirection - The direction of movement on the specified axis.
     * @param firstThreshold - The bounding box representing the first threshold.
     * @param secondThreshold - The bounding box representing the second threshold.
     */
    setZone(axis: Axis, movementDirection: MovementDirection, firstThreshold: BoxNum, secondThreshold: BoxNum): void;
    /**
     * Checks if the dragged element is inside the threshold dead zone.
     *
     * @param axis - The axis along which the movement is occurring ('x' or 'y').
     * @param movementDirection - The direction of movement on the specified axis.
     * @param draggedPos - The position of the dragged element.
     * @returns True if the dragged element is inside the dead zone with matching
     * movement direction, otherwise false.
     */
    isInside(axis: Axis, movementDirection: MovementDirection, draggedPos: BoxNum): boolean;
    /**
     * Clears the area and movement values, resetting them to their initial state.
     */
    clear(): void;
}

declare class DFlexTracker {
    private _travelID;
    /**
     * Creates an instance of Tracker.
     */
    constructor();
    /**
     * Increment travels and return the last one.
     */
    newTravel(prefix: string): string;
}

declare const _default: DFlexTracker;

declare const PREFIX_TRACKER_CYCLE = "dflex_cycle_";
declare const PREFIX_TRACKER_ID = "dflex_id_";
declare const PREFIX_TRACKER_KY = "dflex_ky_";

type QKey = string;
declare class TaskQueue {
    private _elmInQueue;
    private _queue;
    constructor();
    private _intiQueueRecord;
    private _addFuncToQueueRecord;
    _isEmpty(queueKey: string): boolean;
    hasElm(elmKey: string): boolean;
    enqueueBeforeLast(lastElmFn: () => unknown, beforeLastFn: () => unknown, queueKey: QKey, elmKey?: string): void;
    enqueue(fn: () => unknown, queueKey: QKey, elmKey?: string): void;
    /**
     * Executes the queued tasks for the specified queue key, bypassing the scheduled execution.
     *
     * @param queueKey - The key of the queue to execute.
     * @returns An array containing the results of executing the tasks in the queue.
     */
    executeQueue(queueKey: QKey): unknown[];
    private _schedule;
    scheduleNextTask(keys: [QKey, QKey | undefined]): void;
    cancelQueuedTask(): void;
    clear(): void;
}

type DebouncedListener = () => void;
interface DebounceControl extends DebouncedListener {
    isPaused: () => boolean;
    pause: () => void;
    resume: () => void;
}
declare function DFlexEventDebounce(listener: DebouncedListener, immediate?: boolean, throttle?: number): DebounceControl;

declare class AbstractDFlexCycle {
    /** Transitioning element ID. */
    id: string;
    /** Last known index for draggable before transitioning. */
    index: number;
    /** Transition siblings key. */
    SK: string;
    reconciledIDs: Set<string>;
    cycleID: string;
    hasScroll: boolean;
    numberOfTransformedELm: number;
    /** Defined during the transition. */
    marginBottom: number | null;
    /** Defined during the transition. */
    marginTop: number | null;
    constructor(index: number, id: string, SK: string, cycleID: string, hasScroll: boolean);
}
declare class DFlexCycle {
    private _migrations;
    SKs: string[];
    /** Only true when transitioning. */
    isTransitioning: boolean;
    /**
     * Indicates whether an active drag operation is in progress.
     */
    isActive: boolean;
    constructor(index: number, id: string, SK: string, cycleID: string, hasScroll: boolean);
    /** Get the latest migrations instance */
    latest(): AbstractDFlexCycle;
    /** Get the previous migrations instance */
    prev(): AbstractDFlexCycle;
    getAll(): AbstractDFlexCycle[];
    /**
     * Get all cycles filtered by cycleI-IDs or element-IDs.
     *
     * @param cycleIDs
     * @param byCycleID
     * @returns
     */
    filter(cycleIDs: string[], byCycleID: boolean): AbstractDFlexCycle[];
    /**
     * Delete keys from the SKs array.
     *
     * @param keysToDelete - A set of keys to be deleted.
     */
    private _deleteKeysFromSKs;
    flush(cycleIDs: string[]): void;
    pruneSKFromMigration(SK: string): void;
    /**
     * We only update indexes considering migration definition when it happens
     * outside container but not moving inside it.
     * So we update an index but we add key.
     *
     * @param index
     */
    setIndex(index: number): void;
    preserveVerticalMargin(type: "top" | "bottom", m: number | null): void;
    clearMargin(): void;
    /**
     * Add a new migration.
     *
     * @param index - The index of the migration.
     * @param id - The ID of the element.
     * @param SK - The sibling key.
     * @param isAddOperation - Indicates whether the operation is an "add" operation.
     * @param cycleID - The cycle ID.
     * @param hasScroll - Indicates whether the element has a scroll container.
     */
    add(index: number, id: string, SK: string, isAddOperation: boolean, cycleID: string, hasScroll: boolean): void;
    updateReconciledIDs(sk: string, reconciledIDs: Set<string>): void;
    getMigrationBySK(sk: string): AbstractDFlexCycle | undefined;
    /**
     * Get reconciled IDs by sibling key (SK).
     *
     * @param sk - The sibling key for which to retrieve reconciled IDs.
     * @returns A Set of reconciled IDs for the specified sibling key.
     */
    getReconciledIDsBySK(sk: string): Set<string>;
    /**
     * start transitioning
     */
    start(): void;
    /**
     * Get the migration done
     */
    complete(): void;
    clear(): void;
}

type KY = number | string;
declare function combineKeys(k1: KY, k2: KY): string;

declare function warnOnce(caller: string, ...message: any[]): void;

declare function assertElementPosition(DOM: HTMLElement, rect: AbstractBox): void;

declare function getAnimationOptions(animation?: Partial<AnimationOpts> | null): Required<AnimationOpts> | null;

declare function noop(): void;
declare const noopSet: Set<string>;

declare function getDimensionTypeByAxis(axis: Axis): "height" | "width";
declare function getStartingPointByAxis(axis: Axis): "left" | "top";
declare function getEndingPointByAxis(axis: Axis): "right" | "bottom";
declare function getOppositeAxis(axis: Axis): Axis;

declare function setStyleProperty(DOM: HTMLElement, property: string, value: string | null): void;
declare function removeStyleProperty(DOM: HTMLElement, property: string): void;
declare function getCachedComputedStyleProperty(DOM: Element, property: string, toNumber: true): number;
declare function getCachedComputedStyleProperty(DOM: Element, property: string, toNumber: false): string;
declare function clearComputedStyleCache(): void;
declare function getElmDimensions(DOM: HTMLElement): Dimensions;
declare function getParsedElmTransform(DOM: HTMLElement): [number, number] | null;
declare function setFixedDimensions(DOM: HTMLElement): void;
type CSSPosition = "static" | "relative" | "absolute" | "fixed" | "sticky";
declare function getElmPos(DOM: HTMLElement): CSSPosition;
type CSSOverflow = "visible" | "hidden" | "scroll" | "auto" | "overlay";
type CSSOverflowType = "overflow" | "overflow-x" | "overflow-y";
declare function getElmOverflow(DOM: HTMLElement, overflowType: CSSOverflowType): CSSOverflow;
declare function setRelativePosition(DOM: HTMLElement): void;
declare function removeOpacity(DOM: HTMLElement): void;
declare function setParentDimensions(DOM: HTMLElement): void;
declare function hasCSSTransition(DOM: HTMLElement): boolean;
declare function rmEmptyAttr(DOM: HTMLElement, attribute: string): void;

declare function getSelection(): Selection | null;

declare function getParentElm(baseElement: HTMLElement, cb: (arg: HTMLElement) => boolean): null | HTMLElement;

declare function canUseDOM(): boolean;

declare function updateElmDatasetGrid(DOM: HTMLElement, grid: PointNum): void;

declare function updateDOMAttr<T extends string>(DOM: HTMLElement, name: T, isRemove: boolean, addPrefix?: boolean, value?: string | undefined): void;
declare function updateIndexAttr(DOM: HTMLElement, value: number): void;

declare function getElmBoxRect(DOM: HTMLElement, scrollLeft: number, scrollTop: number): BoxRect;

type AnimationFrameCallback = (timestamp: number) => void;
type IsRafDone = () => boolean;
type RAFCleanup = () => void;
type RAFFunction = (callback: AnimationFrameCallback, cancelPrevFrame: boolean) => void;
declare function DFlexCreateRAF(): [RAFFunction, RAFCleanup, IsRafDone];
declare function autoCleanupAllRAFs(): void;

type TimeoutCallback = () => void;
type TimeoutCleanup = () => void;
type TimeoutFunction = (callback: TimeoutCallback | null, cancelPrevSchedule: boolean) => void;
type IsThrottledFunction = () => boolean;
declare function DFlexCreateTimeout(msDelay: number): [TimeoutFunction, TimeoutCleanup, IsThrottledFunction];
declare function autoCleanupAllTimeouts(): void;

/**
 * If true, then DFlex will assert each element position that's change and match
 * with DOM.
 */
declare const enablePositionAssertion = false;
/**
 * If true, then DFlex will override input options and reconcile changes after
 * each cycle.
 */
declare const enableCommit = false;
declare const enableUndoSiblingsDebugger = false;
declare const enableRegisterDebugger = false;
declare const enableMechanismDebugger = false;
declare const enableScrollDebugger = false;
declare const enableVisibilityDebugger = false;
declare const enableMutationDebugger = false;
declare const enableReconcileDebugger = false;

declare const FeatureFlags_enableCommit: typeof enableCommit;
declare const FeatureFlags_enableMechanismDebugger: typeof enableMechanismDebugger;
declare const FeatureFlags_enableMutationDebugger: typeof enableMutationDebugger;
declare const FeatureFlags_enablePositionAssertion: typeof enablePositionAssertion;
declare const FeatureFlags_enableReconcileDebugger: typeof enableReconcileDebugger;
declare const FeatureFlags_enableRegisterDebugger: typeof enableRegisterDebugger;
declare const FeatureFlags_enableScrollDebugger: typeof enableScrollDebugger;
declare const FeatureFlags_enableUndoSiblingsDebugger: typeof enableUndoSiblingsDebugger;
declare const FeatureFlags_enableVisibilityDebugger: typeof enableVisibilityDebugger;
declare namespace FeatureFlags {
  export { FeatureFlags_enableCommit as enableCommit, FeatureFlags_enableMechanismDebugger as enableMechanismDebugger, FeatureFlags_enableMutationDebugger as enableMutationDebugger, FeatureFlags_enablePositionAssertion as enablePositionAssertion, FeatureFlags_enableReconcileDebugger as enableReconcileDebugger, FeatureFlags_enableRegisterDebugger as enableRegisterDebugger, FeatureFlags_enableScrollDebugger as enableScrollDebugger, FeatureFlags_enableUndoSiblingsDebugger as enableUndoSiblingsDebugger, FeatureFlags_enableVisibilityDebugger as enableVisibilityDebugger };
}

export { AbstractBox, type AbstractBoxRect, AbstractDFlexCycle, type AnimationOpts, type Axes, AxesPoint, type Axis, BOTH_AXIS, Box, BoxBool, BoxNum, BoxRect, type CSS, type CSSClass, type CSSStyle, type CubicBezier, DFlexCreateRAF, DFlexCreateTimeout, DFlexCycle, type Dimensions, type Direction, type IsThrottledFunction, PREFIX_TRACKER_CYCLE, PREFIX_TRACKER_ID, PREFIX_TRACKER_KY, Point, PointBool, PointNum, type RAFCleanup, type RAFFunction, TaskQueue, DFlexThreshold as Threshold, ThresholdDeadZone, type ThresholdPercentages, type TimeoutCleanup, type TimeoutFunction, assertElementPosition as assertElmPos, autoCleanupAllRAFs, autoCleanupAllTimeouts, canUseDOM, clearComputedStyleCache, combineKeys, DFlexEventDebounce as eventDebounce, FeatureFlags as featureFlags, getAnimationOptions, getCachedComputedStyleProperty, getDimensionTypeByAxis, getElmBoxRect, getElmDimensions, getElmOverflow, getElmPos, getEndingPointByAxis, getOppositeAxis, getParentElm, getParsedElmTransform, getSelection, getStartingPointByAxis, hasCSSTransition, noop, noopSet, removeOpacity, removeStyleProperty, rmEmptyAttr, setFixedDimensions, setParentDimensions, setRelativePosition, setStyleProperty, _default as tracker, updateDOMAttr, updateElmDatasetGrid, updateIndexAttr, warnOnce };