@andrew_l/dom 0.3.22 → 0.4.0

package/dist/index.d.cts

@@ -1,219 +0,0 @@
-interface AnimationInstance {
-    isCancelled: boolean;
-}
-/**
- * Animates a single tick of an animation, running repeatedly until cancelled or the tick function returns `false`.
- *
- * If an `instance` is provided, it will control the cancellation state of the animation. Otherwise, a new animation
- * instance is created and assigned as the current instance. This function uses `fastRaf` to run the animation in the
- * next available frame.
- *
- * @param tick A function to be called on each frame, returning `true` to continue animating or `false` to stop.
- * @param instance An optional animation instance to control cancellation state.
- *
- * @example
- * animateSingle(() => {
- *   // Your tick logic here (e.g., move an element)
- *   return true; // Return `true` to keep animating, `false` to stop.
- * });
- *
- * @group Animation
- */
-declare function animateSingle(tick: Function, instance?: AnimationInstance): void;
-/**
- * Continuously animates by repeatedly calling the `tick` function until it returns `false`.
- *
- * The function uses `fastRaf` to run the animation and continues until the `tick` function no longer returns `true`.
- *
- * @param tick The tick function to be executed on each frame. If it returns `false`, the animation stops.
- *
- * @example
- * animate(() => {
- *   // Your animation logic here
- *   return true; // Return `true` to continue animating, `false` to stop.
- * });
- *
- * @group Animation
- */
-declare function animate(tick: Function): void;
-/**
- * Instantly animates by calling the `tick` function in rapid succession until it returns `false`.
- *
- * This is intended for scenarios where the animation should run as quickly as possible, without any delay.
- *
- * @param tick The tick function to be executed on each frame. If it returns `false`, the animation stops.
- *
- * @example
- * animateInstantly(() => {
- *   // Your instant animation logic here
- *   return true; // Return `true` to continue animating, `false` to stop.
- * });
- *
- * @group Animation
- */
-declare function animateInstantly(tick: Function): void;
-type TimingFn = (t: number) => number;
-type AnimateNumberProps = {
-    to: number | number[];
-    from: number | number[];
-    duration: number;
-    onUpdate: (value: any) => void;
-    timing?: TimingFn;
-    onEnd?: () => void;
-};
-declare const timingFunctions: {
-    linear: (t: number) => number;
-    easeIn: (t: number) => number;
-    easeOut: (t: number) => number;
-    easeInOut: (t: number) => number;
-    easeInQuad: (t: number) => number;
-    easeOutQuad: (t: number) => number;
-    easeInOutQuad: (t: number) => number;
-    easeInCubic: (t: number) => number;
-    easeOutCubic: (t: number) => number;
-    easeInOutCubic: (t: number) => number;
-    easeInQuart: (t: number) => number;
-    easeOutQuart: (t: number) => number;
-    easeInOutQuart: (t: number) => number;
-    easeInQuint: (t: number) => number;
-    easeOutQuint: (t: number) => number;
-    easeInOutQuint: (t: number) => number;
-};
-/**
- * Animates a numeric value from `from` to `to` over a specified duration, applying an optional timing function.
- *
- * The animation will continuously update the value using the `onUpdate` callback until the animation is complete.
- * Once the animation ends, the `onEnd` callback will be called, if provided.
- *
- * @param timing The timing function that controls the progression of the animation. Defaults to `linear`.
- * @param onUpdate A callback that receives the updated value (or values) on each animation frame.
- * @param duration The duration of the animation in milliseconds.
- * @param onEnd An optional callback to be called when the animation completes.
- * @param from The starting value(s) of the animation.
- * @param to The target value(s) of the animation.
- *
- * @returns A function that can be called to cancel the animation.
- *
- * @example
- * animateNumber({
- *   from: 0,
- *   to: 100,
- *   duration: 1000,
- *   onUpdate: (value) => {
- *     console.log(value); // Updated value on each frame
- *   },
- *   onEnd: () => {
- *     console.log('Animation complete!');
- *   },
- * });
- *
- * @group Animation
- */
-declare function animateNumber({ timing, onUpdate, duration, onEnd, from, to, }: AnimateNumberProps): () => void;
-
-/**
- * Copies the provided text to the system clipboard.
- *
- * The function attempts to use the `navigator.clipboard` API if available. If not,
- * it falls back to using a fake element approach to copy the text.
- *
- * @param text The text to be copied to the clipboard.
- * @returns A promise that resolves to `true` if the text was successfully copied,
- *          or `false` if the operation failed.
- *
- * @example
- * copyTextToClipboard('Hello, World!')
- *   .then(success => {
- *     if (success) {
- *       console.log('Text copied to clipboard!');
- *     } else {
- *       console.log('Failed to copy text.');
- *     }
- *   });
- *
- * @group Clipboard
- */
-declare function copyTextToClipboard(text: string): Promise<boolean>;
-
-declare const FAST_SMOOTH_MAX_DISTANCE = 1500;
-declare const FAST_SMOOTH_MIN_DURATION = 250;
-declare const FAST_SMOOTH_MAX_DURATION = 600;
-declare const FAST_SMOOTH_SHORT_TRANSITION_MAX_DISTANCE = 500;
-type ScrollCompleteCallback = (target: HTMLElement) => void;
-declare enum FocusDirection {
-    Up = 0,
-    Down = 1,
-    Static = 2
-}
-/**
- * Smoothly scrolls the specified container to bring the given element into view,
- * with optional customization for scroll behavior, direction, and duration.
- *
- * This function calculates the optimal scroll position based on the given parameters
- * and smoothly scrolls the container to that position. It can adjust the scroll
- * behavior for accessibility, animation duration, and other constraints.
- *
- * @param container The container element that will be scrolled.
- * @param element The element inside the container that needs to be brought into view.
- * @param position The scroll position logic (`'centerOrTop'`, `ScrollLogicalPosition`).
- * @param margin A margin in pixels to be applied around the element when scrolling into view (default is `0`).
- * @param maxDistance The maximum distance for smooth scrolling (default is `FAST_SMOOTH_MAX_DISTANCE`).
- * @param forceDirection Optional, the direction to force the scroll (`FocusDirection`). If not provided, the default scroll direction is calculated.
- * @param forceDuration Optional, a custom duration (in milliseconds) for the smooth scroll. If not provided, a default duration is used.
- * @param forceNormalContainerHeight Optional, a flag indicating whether to force the container height calculation for normal behavior.
- * @param onComplete Optional callback function that is triggered when the scroll operation completes.
- *
- * @example
- * fastSmoothScroll(container, element, 'centerOrTop', 10, 500, FocusDirection.Up, 300);
- *
- * @group Scrolling
- */
-declare function fastSmoothScroll(container: HTMLElement, element: HTMLElement, position: ScrollLogicalPosition | 'centerOrTop', margin?: number, maxDistance?: number, forceDirection?: FocusDirection, forceDuration?: number, forceNormalContainerHeight?: boolean, onComplete?: ScrollCompleteCallback): void;
-
-/**
- * Determines if the specified element or the document/window is scrolled near the bottom.
- *
- * This function checks if the scroll position has reached the bottom of the target element or window
- * within a specified threshold. It is commonly used for implementing "infinite scroll" or detecting
- * when a user has scrolled to the bottom of a page or container.
- *
- * @param target The target element, document, or window to check the scroll position.
- *               Can be an `HTMLElement`, `Document`, or `Window`.
- * @param threshold The threshold (in pixels) below which the target is considered "scrolled to the bottom."
- *                  Default is `10`, meaning the target is considered scrolled to the bottom if it is within 10px of the bottom.
- *
- * @returns `true` if the target is scrolled near the bottom within the given threshold, otherwise `false`.
- *
- * @example
- * // Check if the window is scrolled near the bottom
- * isScrolledToDown(window, 20); // Returns true if within 20px of the bottom of the window.
- *
- * @example
- * // Check if a specific container is scrolled near the bottom
- * const container = document.getElementById('myContainer');
- * isScrolledToDown(container, 50); // Returns true if within 50px of the bottom of the container.
- *
- * @group Scrolling
- */
-declare function isScrolledToDown(target: HTMLElement | Document | Window, threshold?: number): boolean;
-
-/**
- * Resets the scroll position of the specified container element.
- *
- * If a `scrollTop` value is provided, the container's scroll position is set
- * to that value. Otherwise, the function will leave the scroll position unchanged.
- * This function is useful for resetting the scroll state in a container, such as
- * when the content changes or after an animation.
- *
- * @param container The container element whose scroll position needs to be reset.
- * @param scrollTop Optional value to set the container's `scrollTop`. If not provided, the scroll position remains unchanged.
- *
- * @example
- * resetScroll(container, 0); // Resets scroll to top of the container.
- * resetScroll(container); // Resets scroll position without changing it.
- *
- * @group Scrolling
- */
-declare function resetScroll(container: HTMLDivElement, scrollTop?: number): void;
-
-export { type AnimateNumberProps, FAST_SMOOTH_MAX_DISTANCE, FAST_SMOOTH_MAX_DURATION, FAST_SMOOTH_MIN_DURATION, FAST_SMOOTH_SHORT_TRANSITION_MAX_DISTANCE, FocusDirection, type ScrollCompleteCallback, type TimingFn, animate, animateInstantly, animateNumber, animateSingle, copyTextToClipboard, fastSmoothScroll, isScrolledToDown, resetScroll, timingFunctions };

package/dist/index.d.ts

@@ -1,219 +0,0 @@
-interface AnimationInstance {
-    isCancelled: boolean;
-}
-/**
- * Animates a single tick of an animation, running repeatedly until cancelled or the tick function returns `false`.
- *
- * If an `instance` is provided, it will control the cancellation state of the animation. Otherwise, a new animation
- * instance is created and assigned as the current instance. This function uses `fastRaf` to run the animation in the
- * next available frame.
- *
- * @param tick A function to be called on each frame, returning `true` to continue animating or `false` to stop.
- * @param instance An optional animation instance to control cancellation state.
- *
- * @example
- * animateSingle(() => {
- *   // Your tick logic here (e.g., move an element)
- *   return true; // Return `true` to keep animating, `false` to stop.
- * });
- *
- * @group Animation
- */
-declare function animateSingle(tick: Function, instance?: AnimationInstance): void;
-/**
- * Continuously animates by repeatedly calling the `tick` function until it returns `false`.
- *
- * The function uses `fastRaf` to run the animation and continues until the `tick` function no longer returns `true`.
- *
- * @param tick The tick function to be executed on each frame. If it returns `false`, the animation stops.
- *
- * @example
- * animate(() => {
- *   // Your animation logic here
- *   return true; // Return `true` to continue animating, `false` to stop.
- * });
- *
- * @group Animation
- */
-declare function animate(tick: Function): void;
-/**
- * Instantly animates by calling the `tick` function in rapid succession until it returns `false`.
- *
- * This is intended for scenarios where the animation should run as quickly as possible, without any delay.
- *
- * @param tick The tick function to be executed on each frame. If it returns `false`, the animation stops.
- *
- * @example
- * animateInstantly(() => {
- *   // Your instant animation logic here
- *   return true; // Return `true` to continue animating, `false` to stop.
- * });
- *
- * @group Animation
- */
-declare function animateInstantly(tick: Function): void;
-type TimingFn = (t: number) => number;
-type AnimateNumberProps = {
-    to: number | number[];
-    from: number | number[];
-    duration: number;
-    onUpdate: (value: any) => void;
-    timing?: TimingFn;
-    onEnd?: () => void;
-};
-declare const timingFunctions: {
-    linear: (t: number) => number;
-    easeIn: (t: number) => number;
-    easeOut: (t: number) => number;
-    easeInOut: (t: number) => number;
-    easeInQuad: (t: number) => number;
-    easeOutQuad: (t: number) => number;
-    easeInOutQuad: (t: number) => number;
-    easeInCubic: (t: number) => number;
-    easeOutCubic: (t: number) => number;
-    easeInOutCubic: (t: number) => number;
-    easeInQuart: (t: number) => number;
-    easeOutQuart: (t: number) => number;
-    easeInOutQuart: (t: number) => number;
-    easeInQuint: (t: number) => number;
-    easeOutQuint: (t: number) => number;
-    easeInOutQuint: (t: number) => number;
-};
-/**
- * Animates a numeric value from `from` to `to` over a specified duration, applying an optional timing function.
- *
- * The animation will continuously update the value using the `onUpdate` callback until the animation is complete.
- * Once the animation ends, the `onEnd` callback will be called, if provided.
- *
- * @param timing The timing function that controls the progression of the animation. Defaults to `linear`.
- * @param onUpdate A callback that receives the updated value (or values) on each animation frame.
- * @param duration The duration of the animation in milliseconds.
- * @param onEnd An optional callback to be called when the animation completes.
- * @param from The starting value(s) of the animation.
- * @param to The target value(s) of the animation.
- *
- * @returns A function that can be called to cancel the animation.
- *
- * @example
- * animateNumber({
- *   from: 0,
- *   to: 100,
- *   duration: 1000,
- *   onUpdate: (value) => {
- *     console.log(value); // Updated value on each frame
- *   },
- *   onEnd: () => {
- *     console.log('Animation complete!');
- *   },
- * });
- *
- * @group Animation
- */
-declare function animateNumber({ timing, onUpdate, duration, onEnd, from, to, }: AnimateNumberProps): () => void;
-
-/**
- * Copies the provided text to the system clipboard.
- *
- * The function attempts to use the `navigator.clipboard` API if available. If not,
- * it falls back to using a fake element approach to copy the text.
- *
- * @param text The text to be copied to the clipboard.
- * @returns A promise that resolves to `true` if the text was successfully copied,
- *          or `false` if the operation failed.
- *
- * @example
- * copyTextToClipboard('Hello, World!')
- *   .then(success => {
- *     if (success) {
- *       console.log('Text copied to clipboard!');
- *     } else {
- *       console.log('Failed to copy text.');
- *     }
- *   });
- *
- * @group Clipboard
- */
-declare function copyTextToClipboard(text: string): Promise<boolean>;
-
-declare const FAST_SMOOTH_MAX_DISTANCE = 1500;
-declare const FAST_SMOOTH_MIN_DURATION = 250;
-declare const FAST_SMOOTH_MAX_DURATION = 600;
-declare const FAST_SMOOTH_SHORT_TRANSITION_MAX_DISTANCE = 500;
-type ScrollCompleteCallback = (target: HTMLElement) => void;
-declare enum FocusDirection {
-    Up = 0,
-    Down = 1,
-    Static = 2
-}
-/**
- * Smoothly scrolls the specified container to bring the given element into view,
- * with optional customization for scroll behavior, direction, and duration.
- *
- * This function calculates the optimal scroll position based on the given parameters
- * and smoothly scrolls the container to that position. It can adjust the scroll
- * behavior for accessibility, animation duration, and other constraints.
- *
- * @param container The container element that will be scrolled.
- * @param element The element inside the container that needs to be brought into view.
- * @param position The scroll position logic (`'centerOrTop'`, `ScrollLogicalPosition`).
- * @param margin A margin in pixels to be applied around the element when scrolling into view (default is `0`).
- * @param maxDistance The maximum distance for smooth scrolling (default is `FAST_SMOOTH_MAX_DISTANCE`).
- * @param forceDirection Optional, the direction to force the scroll (`FocusDirection`). If not provided, the default scroll direction is calculated.
- * @param forceDuration Optional, a custom duration (in milliseconds) for the smooth scroll. If not provided, a default duration is used.
- * @param forceNormalContainerHeight Optional, a flag indicating whether to force the container height calculation for normal behavior.
- * @param onComplete Optional callback function that is triggered when the scroll operation completes.
- *
- * @example
- * fastSmoothScroll(container, element, 'centerOrTop', 10, 500, FocusDirection.Up, 300);
- *
- * @group Scrolling
- */
-declare function fastSmoothScroll(container: HTMLElement, element: HTMLElement, position: ScrollLogicalPosition | 'centerOrTop', margin?: number, maxDistance?: number, forceDirection?: FocusDirection, forceDuration?: number, forceNormalContainerHeight?: boolean, onComplete?: ScrollCompleteCallback): void;
-
-/**
- * Determines if the specified element or the document/window is scrolled near the bottom.
- *
- * This function checks if the scroll position has reached the bottom of the target element or window
- * within a specified threshold. It is commonly used for implementing "infinite scroll" or detecting
- * when a user has scrolled to the bottom of a page or container.
- *
- * @param target The target element, document, or window to check the scroll position.
- *               Can be an `HTMLElement`, `Document`, or `Window`.
- * @param threshold The threshold (in pixels) below which the target is considered "scrolled to the bottom."
- *                  Default is `10`, meaning the target is considered scrolled to the bottom if it is within 10px of the bottom.
- *
- * @returns `true` if the target is scrolled near the bottom within the given threshold, otherwise `false`.
- *
- * @example
- * // Check if the window is scrolled near the bottom
- * isScrolledToDown(window, 20); // Returns true if within 20px of the bottom of the window.
- *
- * @example
- * // Check if a specific container is scrolled near the bottom
- * const container = document.getElementById('myContainer');
- * isScrolledToDown(container, 50); // Returns true if within 50px of the bottom of the container.
- *
- * @group Scrolling
- */
-declare function isScrolledToDown(target: HTMLElement | Document | Window, threshold?: number): boolean;
-
-/**
- * Resets the scroll position of the specified container element.
- *
- * If a `scrollTop` value is provided, the container's scroll position is set
- * to that value. Otherwise, the function will leave the scroll position unchanged.
- * This function is useful for resetting the scroll state in a container, such as
- * when the content changes or after an animation.
- *
- * @param container The container element whose scroll position needs to be reset.
- * @param scrollTop Optional value to set the container's `scrollTop`. If not provided, the scroll position remains unchanged.
- *
- * @example
- * resetScroll(container, 0); // Resets scroll to top of the container.
- * resetScroll(container); // Resets scroll position without changing it.
- *
- * @group Scrolling
- */
-declare function resetScroll(container: HTMLDivElement, scrollTop?: number): void;
-
-export { type AnimateNumberProps, FAST_SMOOTH_MAX_DISTANCE, FAST_SMOOTH_MAX_DURATION, FAST_SMOOTH_MIN_DURATION, FAST_SMOOTH_SHORT_TRANSITION_MAX_DISTANCE, FocusDirection, type ScrollCompleteCallback, type TimingFn, animate, animateInstantly, animateNumber, animateSingle, copyTextToClipboard, fastSmoothScroll, isScrolledToDown, resetScroll, timingFunctions };