@rosen-group/ngx-onboarding/types/rosen-group-ngx-onboarding.d.ts

Onboarding module for Angular applications

import * as i0 from '@angular/core';
import { EventEmitter, ErrorHandler, NgZone, OnInit, AfterViewInit, OnDestroy } from '@angular/core';
import { Observable } from 'rxjs';
import { SafeStyle, DomSanitizer } from '@angular/platform-browser';

/**
 * Wrapper for native implementations of querySelector from window.document
 */
declare class BrowserDOMSelectorService {
    private doc;
    constructor(doc: any);
    /** see https://developer.mozilla.org/de/docs/Web/API/Document/querySelectorAll */
    querySelectorAll(cssQuery: string): any[];
    /** see https://developer.mozilla.org/de/docs/Web/API/Document/querySelector */
    querySelector(cssQuery: string): any;
    static ɵfac: i0.ɵɵFactoryDeclaration<BrowserDOMSelectorService, never>;
    static ɵprov: i0.ɵɵInjectableDeclaration<BrowserDOMSelectorService>;
}

declare class OnboardingItemDescription {
    language: string;
    headline: string;
    details: string;
}

declare class OnboardingItem {
    selector: string;
    headline: string;
    details: string;
    textAlign?: 'center' | 'left' | 'right';
    position: string;
    descriptions: Array<OnboardingItemDescription>;
    disableSpotlight: boolean;
    disableBackground: boolean;
    transparentSpotlight: boolean;
    toParent: boolean;
}

declare class VisibleOnboardingItem {
    item?: OnboardingItem;
    element?: HTMLElement;
    constructor(item?: OnboardingItem, element?: HTMLElement);
}

/**
 * Container to pass visible onboarding elements from onboarding service
 * to onboarding component (which can be grouped by their "group" field).
 *
 * Current group of elements can be accessed via currentItems(). Next group can be accessed via nextItems().
 *
 * Container does not have immediate access to grouping keys since elements are stored in jagged array.
 */
declare class OnboardingItemContainer {
    private items;
    private totalCount;
    private currentGroupIndex;
    get isEmpty(): boolean;
    /**
     * Check if there is another group of visible onboarding items
     */
    get hasNext(): boolean;
    /**
     * Return current group of visible onboarding items
     */
    get currentItem(): VisibleOnboardingItem;
    /**
     * Return list of All visible onboarding items (regardless of grouping)
     */
    get allItems(): Array<VisibleOnboardingItem>;
    /**
     * Return count of all items (regardless of grouping)
     */
    get totalLength(): number;
    /**
     * Return next group of visible onboarding items
     */
    nextItem(): VisibleOnboardingItem;
    /**
     * Add new group of items
     */
    add(items: Array<VisibleOnboardingItem>): void;
    /**
     * Clear items from container
     */
    clear(): void;
}

interface OnboardingIconConfiguration {
    /**
     * name of a standard material icon by name (defaults to 'contact_support')
     */
    matIconName?: string;
    /**
     *  Use this for a registered font set (register it in iconRegistry first (see link in class header)
     * e.g. 'fa' (for fontawesome)
     */
    fontSet?: string;
    /**
     *  Use this to select an icon from a fontSet that you register like 'address-book'
     */
    fontIcon?: string;
    /**
     *  Set the name of an svg icon you want to use. Do not forget to register it in the iconregistry for material
     *  for example like this:
     *  ```typescript
     *  iconRegistry.addSvgIcon('onboarding_black',
     *              sanitizer.bypassSecurityTrustResourceUrl('./assets/icons/onboarding_black.svg')
     *  );
     *  ```
     */
    svgIcon?: string;
    /** for the following matBadge* properties see https://material.angular.io/components/badge/overview */
    /**
     * material color for the counter background e.g. primary, accent, warn
     */
    matBadgeColor?: string;
    /**
     * size of the badge e.g. small, medium, large
     */
    matBadgeSize?: string;
    /**
     * above|below and before|after
     */
    matBadgePosition?: string;
}

interface OnboardingTextConfiguration {
    regularFontFamily?: string;
    scriptFontFamily?: string;
}

declare enum OnboardingButtonsPosition {
    BottomRight = 0,
    Bottom = 1,
    BottomLeft = 2,
    Left = 3,
    TopLeft = 4,
    Top = 5,
    TopRight = 6,
    Right = 7
}

/**
 * part of the global onboarding configuration
 * change the position of the 'turn off' and 'next' buttons
 */
interface OnboardingButtonsConfiguration {
    /**
     * position of buttons e.g. top, top-left, left, ...
     */
    position?: OnboardingButtonsPosition;
    /**
     * the distance to the top or bottom border in pixel
     */
    verticalDistanceToBorderInPx?: number;
    /**
     * the distance to the left or right border in pixel
     */
    horizontalDistanceToBorderInPx?: number;
}

/**
 * global configuration parameters for onboarding
 * for icon configuration see: https://material.angular.io/components/icon/overview
 * because the properties below a derived from that behave exactly the same
 */
interface OnboardingConfiguration {
    /**
     * configuration for the onboarding button icon and the icon in the upper left corner
     */
    iconConfiguration?: OnboardingIconConfiguration;
    /**
     * configuration for the font settings
     */
    textConfiguration?: OnboardingTextConfiguration;
    /**
     * configuration for the position of the 'turn off' and 'next' buttons
     */
    buttonsConfiguration?: OnboardingButtonsConfiguration;
}

/**
 * Base class for storing the onboarding item enabled status. Can be overridden with own implementations
 * if you don't want to store the settings in the local storage
 */
declare abstract class EnabledStatusBaseService {
    /**
     * saves the status to a persistent storage
     */
    abstract save(enabled: boolean): void;
    /**
     * loads the status from the persistent storage
     * @returns status (true = enabled, false = disabled)
     */
    abstract load(): Observable<boolean>;
}

/**
 * Base class for storing the onboarding item seen status. Can be overridden with own implementations
 * if you don't want to store the settings in the local storage
 */
declare abstract class SeenSelectorsBaseService {
    /**
     * loads seen items from a persistent storage
     * @returns string array of all seen selectors
     */
    abstract load(): Observable<Array<string>>;
    /**
     * save items to a persistent storage
     */
    abstract save(seenSelectors: Array<string>): void;
}

/**
 * The OnboardingService manages the configuration and the status of the onboarding component.
 *
 * The OnboardingComponent listens to the visibleItemsChanged event and retrieves new onboarding items from the visibleItems object.
 */
declare class OnboardingService {
    private browserDomSelectorService;
    private loadAndSaveSeenSelectorsService;
    private loadAndSaveEnabledStatusService;
    private errorHandler;
    private zone;
    /**
     * Container with currently visible onboarding items (grouped).
     * OnboardingComponent must iterate through these groups.
     *
     * called by OnboardingComponent
     */
    readonly visibleItems: OnboardingItemContainer;
    /**
     * called by OnboardingComponent
     */
    visibleItemsChanged: EventEmitter<any>;
    private addSeenSelectorDebounceSubscription;
    private enabledChangedDebounceSubscription;
    private refreshSubscription;
    private items;
    private seenSelectors;
    private enabled;
    private configuration;
    private readonly defaultConfiguration;
    constructor(browserDomSelectorService: BrowserDOMSelectorService, loadAndSaveSeenSelectorsService: SeenSelectorsBaseService, loadAndSaveEnabledStatusService: EnabledStatusBaseService, errorHandler: ErrorHandler, zone: NgZone);
    /**
     * returns the count of the registered items
     */
    get registeredItemsCount(): number;
    /**
     * Configures the onboarding icons and fonts.
     *
     * If you want to change the default settings, then call this in your module where you import this
     * service as provider and set global defaults like icon properties
     */
    configure(configuration: OnboardingConfiguration): void;
    /** used internal only to retrieve to configuration from configure()*/
    getConfiguration(): OnboardingConfiguration;
    /**
     * registers [[OnboardingItem]]s in items, returns the method to unregister items (e.g. in ngOnDestroy)
     */
    register(items: Array<OnboardingItem>): Function;
    /**
     * Check which onboarding items are visible. Emit visibleItemsChanged event.
     * called by OnboardingComponent
     */
    check(): void;
    /**
     * Mark all visible items as SEEN, remove them from visible list and emit change event.
     * called by OnboardingComponent
     */
    hide(): void;
    /**
     * called by OnboardingComponent
     *
     * Disables the onboarding
     */
    disable(): void;
    /**
     * called by OnboardingComponent
     *
     * Enables the onboarding
     */
    enable(): void;
    /**
     * called by OnboardingComponent
     */
    isEnabled(): boolean;
    /**
     * called by OnboardingComponent
     */
    clearSeenSelectors(): void;
    private init;
    private addToSeenSelectors;
    private seenSelectorsChanged;
    private enabledChanged;
    private getNotSeenItems;
    private startRefreshTimer;
    private loadSeenSelectors;
    private saveSeenSelectors;
    private loadEnabledStatus;
    private saveEnabledStatus;
    static ɵfac: i0.ɵɵFactoryDeclaration<OnboardingService, never>;
    static ɵprov: i0.ɵɵInjectableDeclaration<OnboardingService>;
}

/**
 * onboarding button including context menu
 */
declare class OnboardingButtonComponent {
    private onboardingService;
    /** used by template to apply the customizations on icons */
    iconConfig: OnboardingIconConfiguration;
    constructor(onboardingService: OnboardingService);
    /**
     * if true, the count is visible
     * is true, if the onboarding service is disabled and at least one onboarding item is visible
     */
    get showOnboardingItemCount(): boolean;
    /**
     * gets the visible item count
     */
    get onboardingItemCount(): number;
    /**
     * used by template
     * enables the onboarding service
     */
    enableOnboarding(): void;
    /**
     * disables the onboarding service
     */
    disableOnboarding(): void;
    /**
     * resets the onboarding service
     * removes all selectors from seen selectors
     */
    clearOnboarding(): void;
    /**
     * is true, if the onboarding service is enabled
     */
    isOnboardingEnabled(): boolean;
    static ɵfac: i0.ɵɵFactoryDeclaration<OnboardingButtonComponent, never>;
    static ɵcmp: i0.ɵɵComponentDeclaration<OnboardingButtonComponent, "rosen-onboarding-button", never, {}, {}, never, never, true, never>;
}

/**
 * Main component of the onboarding module.
 * Handles the visualization of the onboarding items
 */
declare class OnboardingComponent implements OnInit, AfterViewInit, OnDestroy {
    onboardingService: OnboardingService;
    private domSanitizer;
    /**
     * current visible onboarding item
     */
    visibleItem: VisibleOnboardingItem;
    /**
     * if true, the "show next" button is visible
     * it false, the "got it" button is visible
     * is true, if there are more items to show
     */
    hasNext: boolean;
    /**
     * Do not assign directly use onboardingSevice.configure
     * Name of the material icon to use (defaults to contact_support) (excludes fontSet,fontIcon and svgIcon)
     **/
    matIconName: string;
    /**
     * Do not assign directly use onboardingSevice.configure
     * icon class for span (bootstrap style) (excludes matIconeName and svgIcon)
     */
    fontSet: string;
    /**
     * Do not assign directly use onboardingSevice.configure
     *  icon class for span (bootstrap style) (excludes matIconeName and svgIcon)
     */
    fontIcon: string;
    /**
     * Do not assign directly use onboardingSevice.configure
     *  name of registered svg icon (excludes matIconeName,fontSet and fontIcon)
     */
    svgIcon: string;
    dynamicCss: SafeStyle;
    private textConfig;
    private buttonConfig;
    private visibleItemsChangedSubscription;
    constructor(onboardingService: OnboardingService, domSanitizer: DomSanitizer);
    ngOnInit(): void;
    ngAfterViewInit(): void;
    ngOnDestroy(): void;
    /**
     * gets the fixed position of the html element
     * used by template to set the position of the spotlight
     */
    getPositionStyle(ele: HTMLElement): any;
    isSpotlightTransparent(item: OnboardingItem): boolean;
    /**
     * used by turn off button in template
     */
    disable(): void;
    /**
     * hide current group (show next one if one is available
     */
    hide(): void;
    buttonsPositionStyle(): any;
    /**
     * Show onboarding item
     */
    private showItem;
    /**
     * Hide SINGLE element without change notification
     */
    private hideItem;
    static ɵfac: i0.ɵɵFactoryDeclaration<OnboardingComponent, never>;
    static ɵcmp: i0.ɵɵComponentDeclaration<OnboardingComponent, "rosen-onboarding", never, {}, {}, never, never, true, never>;
}

/**
 * Module for ngx-onboarding.
 * Import this into your "main" module e.g. AppModule
 */
declare class OnboardingModule {
    static ɵfac: i0.ɵɵFactoryDeclaration<OnboardingModule, never>;
    static ɵmod: i0.ɵɵNgModuleDeclaration<OnboardingModule, never, never, never>;
    static ɵinj: i0.ɵɵInjectorDeclaration<OnboardingModule>;
}

/**
 * Base interface for translatorservice (used for core ngx-onboarding labels)
 */
declare abstract class TranslatorBaseService {
    /**
     * implement an EventEmitter with the language key as one its arguments
     * the argument has the minimium properties lang: string (where lang is the new language code)
     */
    abstract onLangChange: EventEmitter<{
        lang: string;
    }>;
    /**
     * The language (code) currently used
     */
    abstract get currentLang(): string;
    /**
     * Returns a translation instantly from the internal state of loaded translation.
     * the keys (with translation examples in english) are
     'ONBOARDING': 'Onboarding',
     'ONBOARDING_FAILED_TO_LOAD_USER_SETTINGS': 'Failed to load onboarding settings.',
     'ONBOARDING_FAILED_TO_SAVE_USER_SETTINGS': 'Failed to save onboarding settings.',
     'ONBOARDING_GOT_IT_MSG': 'Got it',
     'ONBOARDING_DO_NOT_SHOW_AGAIN_MSG': 'Turn off',
     'ONBOARDING_NEXT_MSG': 'Next',
     'ONBOARDING_ENABLE': 'Turn on',
     'ONBOARDING_DISABLE': 'Turn off',
     'ONBOARDING_CLEAR': 'Reset'
     */
    abstract instant(key: string): string;
}

export { EnabledStatusBaseService, OnboardingButtonComponent, OnboardingButtonsPosition, OnboardingComponent, OnboardingItem, OnboardingModule, OnboardingService, SeenSelectorsBaseService, TranslatorBaseService };