@studiohyperdrive/ngx-inform/types/studiohyperdrive-ngx-inform.d.ts

A lightweight ARIA compliant customizable approach for common and complex inform flows in Angular.

import * as i0 from '@angular/core';
import { OnDestroy, AfterViewInit, EventEmitter, Type, ElementRef, Injector, ViewContainerRef, Provider, InjectionToken } from '@angular/core';
import { Direction } from '@angular/cdk/bidi';
import { AutoFocusTarget } from '@angular/cdk/dialog';
import { Observable } from 'rxjs';

declare class NgxTooltipService implements OnDestroy {
    private readonly configuration;
    private readonly overlayService;
    private readonly overlayPositionBuilder;
    private activeTooltip;
    /**
     * A subject to hold the tooltip events
     */
    private readonly tooltipEventsSubject;
    /**
     * A subject to hold the destroy event
     */
    private readonly onDestroySubject;
    /**
     * The overlayRef used to attach the tooltip too
     */
    private overlayRef;
    /**
     * The position record for the tooltip
     */
    private readonly positionRecord;
    constructor();
    /**
     * Show a tooltip
     *
     * @param tooltip - The configuration of the tooltip
     */
    showToolTip(tooltip: NgxTooltipItem): void;
    /**
     * Removes the tooltip.
     */
    removeToolTip(): void;
    /**
     * Dispatches the tooltip event to the subject
     *
     * @param event - A tooltip event
     */
    setToolTipEvent(event: NgxTooltipEvent): void;
    /**
     * Emit the destroy event
     */
    ngOnDestroy(): void;
    static ɵfac: i0.ɵɵFactoryDeclaration<NgxTooltipService, never>;
    static ɵprov: i0.ɵɵInjectableDeclaration<NgxTooltipService>;
}

/**
 * A wrapper service to Angular CDK Dialog that provides a WCAG/ARIA compliant implementation of modals
 *
 * @export
 * @class NgxModalService
 */
declare class NgxModalService {
    private readonly configuration;
    private readonly dialogService;
    /**
     * A subject that keeps track of whether a modal is currently active
     */
    private hasModalSubject;
    /**
     * An observable that keeps track of whether a modal is currently active.
     */
    readonly hasActiveModal$: Observable<boolean>;
    /**
     * Opens a modal based on the provided options
     *
     * @param {NgxModalOptions<ActionType>} options - The modal options
     */
    open<ActionType extends NgxModalActionType = string, DataType = any>(options: NgxModalOptions<ActionType, DataType>): Observable<ActionType>;
    /**
     * Closes the currently active modal
     *
     * * @param onClose - An optional onClose function
     */
    close(onClose?: () => void): void;
    /**
     * Checks if all the necessary preconditions are met
     *
     * @param options - The options of the modal
     * @param  component - The component we wish to render
     */
    private runARIAChecks;
    /**
     * Creates the modal component
     *
     * @param options - The options of the modal
     * @param  component - The component we wish to render
     */
    private createModalComponent;
    /**
     * Checks if the description is provided when the role requires it
     *
     * @param options - The options of the modal
     */
    private hasRequiredDescription;
    /**
     * Returns a value based on whether one of the overwrites is defined
     *
     * @private
     * @param configurationValue - The overwrite on configuration level
     * @param optionsValue - The overwrite on options level
     * @param defaultValue - The default value if no overwrite was defined
     */
    private getValue;
    static ɵfac: i0.ɵɵFactoryDeclaration<NgxModalService, never>;
    static ɵprov: i0.ɵɵInjectableDeclaration<NgxModalService>;
}

/**
 * An abstract for the NgxTooltipDirective
 */
declare abstract class NgxTooltipAbstractComponent {
    private readonly ngxTooltipService;
    /**
     * Set tooltip as active
     */
    showOnMouseEnter(): void;
    /**
     * Set the tooltip as inactive
     */
    removeOnMouseOut(): void;
    /**
     * The role of the component
     */
    readonly role = "tooltip";
    /**
     * The position class of the tooltip
     */
    positionClass: NgxTooltipPositionClass;
    /**
     * The id of the tooltip
     */
    id: string;
    /**
     * The current position of the tooltip
     */
    position: NgxTooltipPosition;
    /**
     * The text of the tooltip
     */
    text: string;
    constructor(ngxTooltipService: NgxTooltipService);
    static ɵfac: i0.ɵɵFactoryDeclaration<NgxTooltipAbstractComponent, never>;
    static ɵdir: i0.ɵɵDirectiveDeclaration<NgxTooltipAbstractComponent, never, never, { "positionClass": { "alias": "positionClass"; "required": false; }; "id": { "alias": "id"; "required": true; }; "position": { "alias": "position"; "required": true; }; "text": { "alias": "text"; "required": true; }; }, {}, never, never, true, never>;
}

/**
 * An abstract for the NgxModalService
 */
declare class NgxModalAbstractComponent<ActionType extends NgxModalActionType, DataType = any> implements AfterViewInit {
    private readonly windowService;
    private readonly elementRef;
    /**
     * Remove the modal on escape pressed
     */
    protected onEscape(): void;
    /**
     * An optional aria-labelledby property
     */
    ariaLabelledBy: string;
    /**
     * An optional aria-describedBy property
     */
    ariaDescribedBy: string;
    /**
     * Optional data that can be passed to the modal
     */
    data: DataType;
    /**
     * An emitter that will emit an action we can later respond to
     */
    action: EventEmitter<ActionType>;
    /**
     * An emitter that will emit if the modal is closed
     */
    close: EventEmitter<void>;
    ngAfterViewInit(): void;
    static ɵfac: i0.ɵɵFactoryDeclaration<NgxModalAbstractComponent<any, any>, never>;
    static ɵdir: i0.ɵɵDirectiveDeclaration<NgxModalAbstractComponent<any, any>, never, never, { "ariaLabelledBy": { "alias": "ariaLabelledBy"; "required": false; }; "ariaDescribedBy": { "alias": "ariaDescribedBy"; "required": false; }; "data": { "alias": "data"; "required": false; }; }, { "action": "action"; "close": "close"; }, never, never, true, never>;
}

type NgxTooltipPosition = 'above' | 'below' | 'left' | 'right';
type NgxTooltipPositionClass = `ngx-tooltip-position-${NgxTooltipPosition}`;
interface NgxTooltipConfiguration {
    component: Type<NgxTooltipAbstractComponent>;
    defaultPosition?: NgxTooltipPosition;
}
interface NgxTooltipItem {
    text: string;
    id: string;
    elementRef: ElementRef;
    component?: Type<NgxTooltipAbstractComponent>;
    position?: NgxTooltipPosition;
}
interface NgxTooltipBaseEvent {
    source: 'tooltip' | 'element';
    id: string;
    active: boolean;
}
interface NgxTooltipInactiveEvent extends NgxTooltipBaseEvent {
    active: false;
}
interface NgxTooltipActiveElementEvent extends NgxTooltipBaseEvent {
    active: true;
    source: 'element';
    elementRef: ElementRef;
    component?: Type<NgxTooltipAbstractComponent>;
    position?: NgxTooltipPosition;
    text: string;
}
interface NgxTooltipActiveTooltipEvent extends NgxTooltipBaseEvent {
    active: true;
    source: 'tooltip';
}
type NgxTooltipEvent = NgxTooltipInactiveEvent | NgxTooltipActiveElementEvent | NgxTooltipActiveTooltipEvent;

type NgxModalRole = 'dialog' | 'alertdialog';
/**
 * The type of action that should be emitted by the modal.
 */
type NgxModalActionType<StringType extends string = string, EmitDataType = any> = StringType | {
    type: StringType;
    data: EmitDataType;
};
interface NgxModalAriaLabelBaseOptions {
    /**
     * The label passed to the modal.
     */
    label?: string;
    /**
     * The ID of the element that labels the modal.
     * From the [Mozilla docs](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby):
     *
     * *It should reference brief text that provides the element with an accessible name.
     * [...] a label describes the essence of an object.*
     */
    labelledById?: string;
}
interface NgxModalAriaLabelOptions extends NgxModalAriaLabelBaseOptions {
    label: string;
    labelledById?: undefined;
}
interface NgxModalAriaLabelledOptions extends NgxModalAriaLabelBaseOptions {
    label?: undefined;
    labelledById: string;
}
type NgxModalLabelAriaOptions = NgxModalAriaLabelOptions | NgxModalAriaLabelledOptions;
interface NgxModalGlobalCDKConfiguration {
    /**
     * Whether the modal should close on navigation.
     */
    closeOnNavigation?: boolean;
    /**
     * The direction of the modal.
     */
    direction?: Direction;
    /**
     * Whether the modal has a backdrop.
     */
    hasBackdrop?: boolean;
    /**
     * The class that should be applied to the modal.
     */
    panelClass?: string | string[];
    /**
     * Whether the modal should close when an event is fired.
     */
    autoClose?: boolean;
}
interface NgxModalCDKModalConfiguration {
    /**
     *  The Injector used for the instantiation of the component to be attached.
     * If provided, takes precedence over the injector indirectly provided by
     * the ViewContainerRef. This will allow for host-service injection to
     * the component.
     */
    injector?: Injector;
    /**
     * Where the attached component should live in Angular's logical component tree.
     * This affects what is available for injection and the change detection order
     * for the component instantiated inside of the dialog. This does not affect
     * where the dialog content will be rendered in the DOM.
     */
    viewContainerRef?: ViewContainerRef;
    /**
     * Whether the dialog should restore focus to the previously-focused element
     * upon closing.
     */
    restoreFocus?: boolean | string | HTMLElement;
    /**
     * Where (or whether) the dialog should focus after it is opened.
     */
    autoFocus?: AutoFocusTarget | string | boolean;
}
interface NgxModalComponentConfiguration<ActionType extends NgxModalActionType, DataType> {
    /**
     * The component that should be rendered as the modal. This component must extend the
     * [`NgxModalAbstractComponent`](../abstracts/modal/modal.abstract.component.ts).
     */
    component: Type<NgxModalAbstractComponent<ActionType, DataType>>;
    /**
     * The role that should be applied to the modal.
     *
     * If the role is set to `alertdialog`, the modal indicates an alert or a message that
     * requires user interaction (e.g. a dismiss / proceed dialog).
     * If the role is set to `dialog`, the modal indicates a dialog that requires user
     * attention, but no interaction. (e.g. an advertisement).
     */
    role: NgxModalRole;
    /**
     * The data that will be passed to the modal. This data will be accessible in the
     * provided component.
     */
    data?: DataType;
}
interface NgxModalBaseConfiguration {
    /**
     * The global modals that were configured in the root of the application.
     */
    modals?: Record<string, NgxModalComponentConfiguration<NgxModalActionType, any> & NgxModalGlobalCDKConfiguration>;
}
type NgxModalConfiguration = NgxModalBaseConfiguration & NgxModalGlobalCDKConfiguration;
interface NgxModalBaseOptions<ActionType extends NgxModalActionType, DataType> {
    /**
     * The name of a config object defined in the global config at the root of
     * the project.
     *
     * If a `component` value is provided alongside a `type` in the local config, the
     * `component` value will take precedence.
     */
    type?: string;
    /**
     * The component that should be rendered as the modal. This component must extend the
     * [`NgxModalAbstractComponent`](../abstracts/modal/modal.abstract.component.ts).
     *
     * This property will take precedence over the `type` property.
     */
    component?: Type<NgxModalAbstractComponent<ActionType, DataType>>;
    /**
     * The data that will be passed to the modal. This data will be accessible in the
     * provided component.
     */
    data?: DataType;
    /**
     * The method that should be called when the modal is closed.
     */
    onClose?: () => void;
    /**
     * The ID of the element that describes the dialog.
     * From the [Mozilla docs](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby):
     *
     * *[...] [it] lists the ids of the descriptions or elements providing more information
     * that the user might need.*
     */
    describedById?: string;
}
interface NgxModalTypeOptions<ActionType extends NgxModalActionType, DataType> extends NgxModalBaseOptions<ActionType, DataType> {
    type: string;
    component?: undefined;
    role?: undefined;
}
interface NgxModalComponentOptions<ActionType extends NgxModalActionType, DataType> extends NgxModalBaseOptions<ActionType, DataType> {
    type?: undefined;
    component: Type<NgxModalAbstractComponent<ActionType, DataType>>;
    /**
     * The role that should be applied to the modal.
     *
     * If the role is set to `alertdialog`, the modal indicates an alert or a message that
     * requires user interaction (e.g. a dismiss / proceed dialog).
     * If the role is set to `dialog`, the modal indicates a dialog that requires user
     * attention, but no interaction. (e.g. an advertisement).
     */
    role: NgxModalRole;
}
type NgxModalOptions<ActionType extends NgxModalActionType = string, DataType = any> = (NgxModalTypeOptions<ActionType, DataType> & NgxModalLabelAriaOptions & NgxModalGlobalCDKConfiguration & NgxModalCDKModalConfiguration) | (NgxModalComponentOptions<ActionType, DataType> & NgxModalLabelAriaOptions & NgxModalGlobalCDKConfiguration & NgxModalCDKModalConfiguration);

/**
 * A directive that adds a ARIA compliant tooltip to a component
 *
 * @export
 * @class NgxTooltipDirective
 */
declare class NgxTooltipDirective {
    private readonly tooltipService;
    private readonly elementRef;
    /**
     * Show the tooltip on hover
     */
    showOnMouseEnter(): void;
    /**
     * Show the tooltip on focus
     */
    showOnFocus(): void;
    /**
     * Remove the tooltip on leaving hover
     */
    removeOnMouseOut(): void;
    /**
     * Remove the tooltip on blur
     */
    removeOnBlur(): void;
    /**
     * Remove the tooltip on escape pressed
     */
    onEscape(): void;
    /**
     * Make the item tabbable
     */
    protected readonly index = 0;
    /**
     * The id of the tooltip, unique in the DOM, required for accessibility. By default, this is an autogenerated UUID.
     */
    ngxTooltipId: string;
    /**
     * The text of the tooltip
     */
    ngxTooltip: string;
    /**
     * An optional component we can pass to replace the default configured component
     */
    ngxTooltipComponent: Type<NgxTooltipAbstractComponent>;
    /**
     * An optional position we can pass to tooltip, by default this is 'above'.
     */
    ngxTooltipPosition: NgxTooltipPosition;
    /**
     * Prevent the tooltip from being shown, by default this is false.
     */
    ngxTooltipDisabled: boolean;
    /**
     * Show the tooltip if it is not visible yet
     */
    private showTooltip;
    /**
     * Remove the tooltip
     */
    private removeTooltip;
    static ɵfac: i0.ɵɵFactoryDeclaration<NgxTooltipDirective, never>;
    static ɵdir: i0.ɵɵDirectiveDeclaration<NgxTooltipDirective, "[ngxTooltip]", never, { "ngxTooltipId": { "alias": "ngxTooltipId"; "required": false; }; "ngxTooltip": { "alias": "ngxTooltip"; "required": true; }; "ngxTooltipComponent": { "alias": "ngxTooltipComponent"; "required": false; }; "ngxTooltipPosition": { "alias": "ngxTooltipPosition"; "required": false; }; "ngxTooltipDisabled": { "alias": "ngxTooltipDisabled"; "required": false; }; }, {}, never, never, true, never>;
}

/**
 * Provides the configuration for the NgxTooltipDirective
 *
 * @param configuration - The required configuration
 */
declare const provideNgxTooltipConfiguration: (configuration: NgxTooltipConfiguration) => Provider;

/**
 * Provides the configuration for the NgxModalService
 *
 * @param configuration - The required configuration
 */
declare const provideNgxModalConfiguration: (configuration: NgxModalConfiguration) => Provider;

/**
 * A token to provide the necessary configuration to the NgxTooltipDirective. This is exported
 * due to testing frameworks (like Storybook) not being able to resolve the InjectionToken in the
 * `provideNgxTooltipConfiguration`.
 */
declare const NgxTooltipConfigurationToken: InjectionToken<NgxTooltipConfiguration>;

/**
 * A token to provide the optional configuration to the NgxModalService
 */
declare const NgxModalConfigurationToken: InjectionToken<NgxModalConfiguration>;

export { NgxModalAbstractComponent, NgxModalConfigurationToken, NgxModalService, NgxTooltipAbstractComponent, NgxTooltipConfigurationToken, NgxTooltipDirective, provideNgxModalConfiguration, provideNgxTooltipConfiguration };
export type { NgxModalActionType, NgxModalComponentConfiguration, NgxModalConfiguration, NgxModalOptions, NgxModalRole, NgxTooltipConfiguration, NgxTooltipEvent, NgxTooltipItem, NgxTooltipPosition, NgxTooltipPositionClass };