ngx-page-scroll-core/index.d.ts

Animated scrolling functionality for angular written in pure typescript

import * as i0 from '@angular/core';
import { ModuleWithProviders, InjectionToken, EventEmitter } from '@angular/core';

/**
 * Examples may be found at https://github.com/gdsmith/jquery.easing/blob/master/jquery.easing.js
 * or http://gizma.com/easing/
 * @param t current time
 * @param b beginning value
 * @param c change In value
 * @param d duration
 */
declare type EasingLogic = (t: number, b: number, c: number, d: number) => number;

interface PageScrollConfig {
    /**
     * The number of milliseconds to wait till updating the scroll position again.
     * Small amounts may produce smoother animations but require more processing power.
     */
    _interval?: number;
    /**
     * The amount of pixels that need to be between the current scrollTop/scrollLeft position
     * and the target position the cause a scroll animation. In case distance is below
     * this threshold, an immediate jump will be performed.
     * Due to dpi or rounding irregularities in browsers floating point numbers for scrollTop/scrollLeft values
     * are possible, making a === comparison of current scrollTop or scrollLeft and target scrollPosition error-prone.
     */
    _minScrollDistance?: number;
    /**
     * How many console logs should be emitted. Also influenced by angular mode (dev or prod mode)
     * 0: No logs, neither in dev nor in prod mode
     * 1: Animation errors in dev mode, no logs in prod mode
     * 2: Animation errors in dev and prod mode
     * 5: Animation errors in dev and all scroll position values that get set; animation errors in prod mode
     */
    _logLevel?: number;
    /**
     * Name of the default namespace.
     */
    namespace?: string;
    /**
     * Whether by default the scrolling should happen in vertical direction (by manipulating the scrollTop property)
     * (= true; default) or in horizontal direction (by manipulating the scrollLeft property) (= false
     */
    verticalScrolling?: boolean;
    /**
     * The duration how long a scrollTo animation should last by default.
     * May be overridden using the page-scroll-duration attribute on a single ngxPageScroll instance.
     */
    duration?: number;
    /**
     * The distance in pixels above scroll target where the animation should stop. Setting a positive number results in
     * the scroll target being more in the middle of the screen, negative numbers will produce scrolling "too far"
     */
    scrollOffset?: number;
    /**
     * Whether by default for inline scroll animations the advanced offset calculation should take place (true) or
     * not (false). Default is false.
     * The advanced offset calculation will traverse the DOM tree upwards, starting at the scrollTarget, until it finds
     * the scrollingView container element. Along the way the offset positions of the relative positioned
     * (position: relative) elements will be taken into account for calculating the target elements position.
     */
    advancedInlineOffsetCalculation?: boolean;
    /**
     * The events that are listened to on the body to decide whether a scroll animation has been interfered/interrupted by the user
     */
    interruptEvents?: string[];
    /**
     * The keys that are considered to interrupt a scroll animation (mainly the arrow keys). All other key presses will not stop the
     * scroll animation.
     */
    interruptKeys?: string[];
    /**
     * Whether a scroll animation should be interruptible by user interaction (true) or not (false). If the user performs an
     * interrupting event while a scroll animation takes place, the scroll animation stops.
     */
    interruptible?: boolean;
    /**
     * Whether the scroll animation should take place if the target is already in the view (true). If set to false the scroll
     * animation will not start, in case the target pixel is already inside the current view.
     */
    scrollInView?: boolean;
    /**
     * Easing logic to be applied when performing the scroll animation
     */
    easingLogic?: EasingLogic;
}

declare class NgxPageScrollCoreModule {
    static forRoot(config?: PageScrollConfig): ModuleWithProviders<NgxPageScrollCoreModule>;
    static ɵfac: i0.ɵɵFactoryDeclaration<NgxPageScrollCoreModule, never>;
    static ɵmod: i0.ɵɵNgModuleDeclaration<NgxPageScrollCoreModule, never, never, never>;
    static ɵinj: i0.ɵɵInjectorDeclaration<NgxPageScrollCoreModule>;
}

declare const NGXPS_CONFIG: InjectionToken<PageScrollConfig>;
declare const defaultPageScrollConfig: PageScrollConfig;

declare type PageScrollTarget = HTMLElement | string;

declare type PageScrollViews = HTMLElement | Document | HTMLBodyElement | Node;

/**
 * An Interface specifying the possible options to be passed into the newInstance() factory method
 */
interface PageScrollOptions extends PageScrollConfig {
    /**
     * The document object of the current app
     */
    document: Document;
    /**
     * A specification of the DOM element to scroll to. Either a string referring to an
     * element using a valid css selector (`#target`, `.class`, `div.class`) or a HTMLElement
     * that is attached to the document's DOM tree.
     */
    scrollTarget: PageScrollTarget;
    /**
     * Array of HTMLElements or the body object that should be manipulated while performing
     * the scroll animation.
     */
    scrollViews?: PageScrollViews[];
    /**
     * Maximum speed to be used for the scroll animation. Only taken
     * into account of no duration is provided
     */
    speed?: number;
    /**
     * A listener to be called whenever the scroll animation stops
     */
    scrollFinishListener?: EventEmitter<boolean>;
    namespace?: string;
    verticalScrolling?: boolean;
    duration?: number;
    scrollOffset?: number;
    advancedInlineOffsetCalculation?: boolean;
    interruptEvents?: string[];
    interruptKeys?: string[];
    interruptible?: boolean;
    scrollInView?: boolean;
    easingLogic?: EasingLogic;
}
/**
 * Represents a scrolling action
 */
declare class PageScrollInstance {
    pageScrollOptions: PageScrollOptions;
    private isInlineScrolling;
    private interruptListener;
    /**
     * These properties will be set/manipulated if the scroll animation starts
     */
    startScrollPosition: number;
    targetScrollPosition: number;
    distanceToScroll: number;
    startTime: number;
    endTime: number;
    executionDuration: number;
    interruptListenersAttached: boolean;
    timer: any;
    /**
     * Private constructor, requires the properties assumed to be the bare minimum.
     * Use the factory methods to create instances:
     *      {@link PageScrollService#create}
     */
    constructor(pageScrollOptions: PageScrollOptions);
    private static getScrollingTargetPosition;
    private static getInlineScrollingTargetPosition;
    getScrollPropertyValue(scrollingView: any): number;
    getScrollClientPropertyValue(scrollingView: any): number;
    /**
     * Extract the exact location of the scrollTarget element.
     *
     * Extract the scrollTarget HTMLElement from the given PageScrollTarget object. The latter one may be
     * a string like "#heading2", then this method returns the corresponding DOM element for that id.
     *
     */
    extractScrollTargetPosition(): {
        top: number;
        left: number;
    };
    /**
     * Get the top offset of the scroll animation.
     * This automatically takes the offset location of the scrolling container/scrolling view
     * into account (for nested/inline scrolling).
     */
    getCurrentOffset(): number;
    /**
     * Sets the "scrollTop" or "scrollLeft" property for all scrollViews to the provided value
     * @return true if at least for one ScrollTopSource the scrollTop/scrollLeft value could be set and it kept the new value.
     *          false if it failed for all ScrollViews, meaning that we should stop the animation
     *          (probably because we're at the end of the scrolling region)
     */
    setScrollPosition(position: number): boolean;
    /**
     * Trigger firing a animation finish event
     * @param value Whether the animation finished at the target (true) or got interrupted (false)
     */
    fireEvent(value: boolean): void;
    /**
     * Attach the interrupt listeners to the PageScrollInstance body. The given interruptReporter
     * will be called if any of the attached events is fired.
     *
     * Possibly attached interruptListeners are automatically removed from the body before the new one will be attached.
     */
    attachInterruptListeners(interruptReporter: InterruptReporter): void;
    /**
     * Remove event listeners from the body and stop listening for events that might be treated as "animation
     * interrupt" events.
     */
    detachInterruptListeners(): void;
    private getScrollTargetElement;
}
/**
 * An Interface a listener should implement to be notified about possible interrupt events
 * that happened due to user interaction while a scroll animation takes place.
 *
 * The PageScrollService provides an implementation to a PageScrollInstance to be notified
 * about scroll animation interrupts and stop related animations.
 */
interface InterruptReporter {
    report(event: Event, pageScrollInstance: PageScrollInstance): void;
}

declare class PageScrollService {
    private readonly config;
    private runningInstances;
    private onInterrupted;
    private stopInternal;
    create(options: PageScrollOptions): PageScrollInstance;
    /**
     * Start a scroll animation. All properties of the animation are stored in the given {@link PageScrollInstance} object.
     *
     * This is the core functionality of the whole library.
     */
    start(pageScrollInstance: PageScrollInstance): void;
    scroll(options: PageScrollOptions): void;
    /**
     * Stop all running scroll animations. Optionally limit to stop only the ones of specific namespace.
     */
    stopAll(namespace?: string): boolean;
    stop(pageScrollInstance: PageScrollInstance): boolean;
    constructor(customConfig: PageScrollConfig);
    static ɵfac: i0.ɵɵFactoryDeclaration<PageScrollService, never>;
    static ɵprov: i0.ɵɵInjectableDeclaration<PageScrollService>;
}

export { NGXPS_CONFIG, NgxPageScrollCoreModule, PageScrollInstance, PageScrollService, defaultPageScrollConfig };
export type { EasingLogic, InterruptReporter, PageScrollConfig, PageScrollOptions, PageScrollTarget, PageScrollViews };