Toast — API · Koobiq

import { KbqToastModule } from '@koobiq/components/toast';

Components

KbqToastComponent

component

 @Component({ selector: 'kbq-toast' })
class KbqToastComponent {
    readonly data: KbqToastData;
    readonly hovered: Signal<boolean>;
    readonly focused: Signal<boolean>;
    id: number;
    readonly $implicit: this;
    get isFocusedOrHovered(): boolean;
    close(): void;
}

hoveredCopy link to hoveredSignal<boolean>: Whether the pointer is over the toast.
focusedCopy link to focusedSignal<boolean>: Whether the toast or an element inside it holds the focus.
$implicitCopy link to $implicitthis: Context of the templates a consumer passes through KbqToastData.

KbqToastContainerComponent

component

 @Component({ selector: 'kbq-toast-container' })
class KbqToastContainerComponent extends CdkScrollable {
    readonly service: KbqToastService<any>;
    readonly viewContainer: Signal<ViewContainerRef>;
    createToast<C>(
        data: KbqToastData,
        componentType: Type<C>,
        onTop: boolean
    ): ComponentRef<C>;
    createTemplate(
        data: KbqToastData,
        template: TemplateRef<any>,
        onTop: boolean
    ): EmbeddedViewRef<KbqToastTemplateContext>;
    remove(viewRef: ViewRef): void;
    getInjector(data: KbqToastData): Injector;
    elementScrolled(): Observable<Event>;
    getElementRef(): ElementRef<HTMLElement>;
    scrollTo(options: ExtendedScrollToOptions): void;
    measureScrollOffset(
        from: "top" | "right" | "left" | "bottom" | "start" | "end"
    ): number;
}

elementScrolled()

Observable<Event>

Returns observable that emits when a scroll event is fired on the host element.

getElementRef()

ElementRef<HTMLElement>

Gets the ElementRef for the viewport.

scrollTo()

void

Scrolls to the specified offsets. This is a normalized version of the browser's native scrollTo method, since browsers are not consistent about what scrollLeft means in RTL. For this method left and right always refer to the left and right side of the scrolling container irrespective of the layout direction. start and end refer to left and right in an LTR context and vice-versa in an RTL context.

Parameters

optionsExtendedScrollToOptions: specified the offsets to scroll to.

measureScrollOffset()

number

Measures the scroll offset relative to the specified edge of the viewport. This method can be used instead of directly checking scrollLeft or scrollTop, since browsers are not consistent about what scrollLeft means in RTL. The values returned by this method are normalized such that left and right always refer to the left and right side of the scrolling container irrespective of the layout direction. start and end refer to left and right in an LTR context and vice-versa in an RTL context.

Parameters

from"top" | "right" | "left" | "bottom" | "start" | "end": The edge to measure from.

Directives

KbqToastCloseButton

directive

 @Directive({ selector: '[kbq-toast-close-button]' })
class KbqToastCloseButton {}

Services

KbqToastService

service

Generic T is a type hint only; the runtime component comes from KBQ_TOAST_FACTORY.

 @Injectable({ providedIn: 'root' })
class KbqToastService<T extends KbqToastComponent = KbqToastComponent> implements KbqToastStack {
    get toasts(): ComponentRef<T>[];
    get templates(): EmbeddedViewRef<KbqToastTemplateContext>[];
    readonly read: BehaviorSubject<KbqToastData | null>;
    readonly hovered: Signal<boolean>;
    readonly focused: Signal<boolean>;
    readonly timer: Observable<number>;
    show(
        data: KbqToastData,
        duration?: number,
        onTop?: boolean
    ): { ref: ComponentRef<T>; id: number };
    showTemplate(
        data: KbqToastData,
        template: TemplateRef<any>,
        duration?: number,
        onTop?: boolean
    ): { ref: EmbeddedViewRef<KbqToastTemplateContext>; id: number };
    hide(id: number): void;
    hideTemplate(id: number): void;
}

hoveredCopy link to hoveredSignal<boolean>: Whether at least one toast is hovered.
focusedCopy link to focusedSignal<boolean>: Whether at least one toast holds the focus.
timerCopy link to timerObservable<number>: Countdown heartbeat: emits every 500 ms while the stack holds something and is not paused by the pointer or the keyboard focus. No interval runs while the stack is empty.

Classes

KbqToastData

class

 class KbqToastData {
    id?: string;
    title?: string | TemplateRef<any>;
    style?: KbqToastStyle | (string & {});
    icon?: TemplateRef<any> | boolean;
    iconClass?: string;
    caption?: string | TemplateRef<any>;
    content?: string | TemplateRef<any>;
    actions?: TemplateRef<any>;
    closeButton?: TemplateRef<any> | boolean;
}

styleoptionalCopy link to styleKbqToastStyle | (string & {}): Visual style of the toast. Styles outside KbqToastStyle render without a default icon.

Types

KbqToastConfig

interface

 interface KbqToastConfig {
    position: KbqToastPosition;
    duration: number;
    delay: number;
    onTop: boolean;
    indent: {
        vertical: number;
        horizontal: number;
    };
}

indentCopy link to indent{ vertical: number; horizontal: number; }: Custom indentation for positioning the toast stack overlay when using GlobalPositionStrategy
indent.verticalCopy link to indent.verticalnumber: Vertical spacing from the top or bottom of the screen.
indent.horizontalCopy link to indent.horizontalnumber: Horizontal spacing from the left or right of the screen.

KbqToastStack

interface

Narrow contract that a toast consumes from the service owning its stack.

KbqToastService implements it and provides itself under KBQ_TOAST_STACK for every toast it creates, so that a toast never has to depend on the concrete service that instantiates it.

 interface KbqToastStack {
    readonly read: Subject<KbqToastData | null>;
    hide(id: number): void;
    setHovered(id: number, hovered: boolean): void;
    setFocused(id: number, origin: FocusOrigin): void;
}

readCopy link to readSubject<KbqToastData | null>: Emits the data of a toast once the user has read it.
hide()Copy link to hide()void: Removes the toast with the given id from the stack.
setHovered()Copy link to setHovered()void: Reports that the pointer entered or left the toast with the given id.
setFocused()Copy link to setFocused()void: Reports the origin the toast with the given id is focused with, or null once it loses focus.

KbqToastTemplateContext

type

Context of a template rendered by KbqToastService.showTemplate.

Note that it differs from the context of the slot templates passed through KbqToastData (title, caption, content, actions, icon and close button), whose $implicit is the KbqToastComponent instance.

 type KbqToastTemplateContext = {
    $implicit: KbqToastData;
};

Enums

KbqToastPosition

enum

 enum KbqToastPosition {
    TOP_RIGHT = 'top-right',
    TOP_LEFT = 'top-left',
    TOP_CENTER = 'top-center',
    BOTTOM_RIGHT = 'bottom-right',
    BOTTOM_LEFT = 'bottom-left',
    BOTTOM_CENTER = 'bottom-center',
    CENTER = 'center'
}

KbqToastStyle

enum

 enum KbqToastStyle {
    Contrast = 'contrast',
    Success = 'success',
    Warning = 'warning',
    Error = 'error'
}

Constants

defaultToastConfig

const

Frozen so that the fallback every application shares cannot be reconfigured from a single consumer.

const defaultToastConfig: KbqToastConfig;

KBQ_TOAST_CONFIG

const

const KBQ_TOAST_CONFIG: InjectionToken<KbqToastConfig>;

KBQ_TOAST_FACTORY

const

const KBQ_TOAST_FACTORY: InjectionToken<typeof KbqToastComponent>;

KBQ_TOAST_STACK

const

Stack a toast belongs to. Provided by KbqToastService for every toast it creates.

const KBQ_TOAST_STACK: InjectionToken<KbqToastStack>;

kbqToastConfigurationProvider

const

Utility provider for KBQ_TOAST_CONFIG.

 const kbqToastConfigurationProvider: (
    configuration: Partial<KbqToastConfig>
) => Provider;

If you found a mistake or want to improve the article, create an issue on GitHub.