ng-hub-ui-avatar/types/ng-hub-ui-avatar.d.ts

A universal avatar component for Angular applications that fetches / generates avatar based on the information you have about the user. Supports initials, Gravatar integration, custom images and styling options. Perfect for user profiles and comment syste

import * as _angular_core from '@angular/core';
import { AfterContentInit, OnChanges, OnDestroy, SimpleChanges, ModuleWithProviders, EnvironmentProviders } from '@angular/core';
import { SafeUrl, DomSanitizer } from '@angular/platform-browser';
import { HttpClient } from '@angular/common/http';
import { Observable } from 'rxjs';

declare enum AvatarSource {
    FACEBOOK = "facebook",
    GRAVATAR = "gravatar",
    GITHUB = "github",
    CUSTOM = "custom",
    INITIALS = "initials",
    VALUE = "value"
}

/**
 * Represents avatar configuration object.
 */
interface AvatarConfig {
    /**
     * The avatars colors.
     */
    colors?: string[];
    /**
     * The order in which the avatar sources will be used.
     */
    sourcePriorityOrder?: AvatarSource[];
    /**
     * Disable custom source (for custom images) cache.
     */
    disableSrcCache?: boolean;
}

declare class AvatarConfigService {
    userConfig: AvatarConfig;
    constructor(userConfig: AvatarConfig);
    getAvatarSources(defaultSources: AvatarSource[]): AvatarSource[];
    getAvatarColors(defaultColors: string[]): string[];
    getDisableSrcCache(defaultDisableSrcCache: boolean): boolean;
    static ɵfac: _angular_core.ɵɵFactoryDeclaration<AvatarConfigService, [{ optional: true; }]>;
    static ɵprov: _angular_core.ɵɵInjectableDeclaration<AvatarConfigService>;
}

/**
 * Contract of all Sources.
 * Every source must implements the fetch method
 * in order to provide the avatar source.
 */
interface Source {
    /**
     * The avatar source type (Facebook, Twitter, etc.).
     */
    readonly sourceType: AvatarSource;
    /**
     * The avatar id in which it's source recognizes it.
     */
    sourceId: string;
    /**
     * Gets the avatar that usually is a URL, but,
     * for example it can also be a string of initials from the name.
     */
    getAvatar(size: number): string;
}

/**
 * list of Supported avatar sources
 */
declare const defaultSources: AvatarSource[];
/**
 * list of default colors
 */
declare const defaultColors: string[];
/**
 * Default disable custom source cache settings
 */
declare const defaultDisableSrcCache = false;
/**
 * Provides utilities methods related to Avatar component
 */
declare class AvatarService {
    private http;
    private avatarConfigService;
    avatarSources: AvatarSource[];
    avatarColors: string[];
    private readonly failedSources;
    constructor(http: HttpClient, avatarConfigService: AvatarConfigService);
    fetchAvatar(avatarUrl: string): Observable<unknown>;
    getRandomColor(avatarText: string): string;
    compareSources(sourceType1: AvatarSource, sourceType2: AvatarSource): number;
    isSource(source: string): boolean;
    isTextAvatar(sourceType: AvatarSource): boolean;
    private buildSourceKey;
    sourceHasFailedBefore(source: Source): boolean;
    markSourceAsFailed(source: Source): void;
    private overrideAvatarSources;
    private overrideAvatarColors;
    private calculateAsciiCode;
    private getSourcePriority;
    static ɵfac: _angular_core.ɵɵFactoryDeclaration<AvatarService, never>;
    static ɵprov: _angular_core.ɵɵInjectableDeclaration<AvatarService>;
}

/**
 * Factory class that implements factory method pattern.
 * Used to create Source implementation class based
 * on the source Type
 */
declare class SourceFactory {
    private sources;
    constructor(avatarConfigService: AvatarConfigService);
    newInstance(sourceType: AvatarSource, sourceValue: string): Source;
    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SourceFactory, never>;
    static ɵprov: _angular_core.ɵɵInjectableDeclaration<SourceFactory>;
}

type StyleObject = Record<string, string | number | null | undefined>;
type Style = StyleObject | string;
/**
 * Semantic colours for the avatar badge and the avatar colour variants. Each maps
 * to a design-system `--hub-sys-color-*` token. Use them to colour a presence dot
 * (e.g. `success` = online, `warning` = away, `danger` = busy, `secondary` = offline)
 * or a labelled badge. Any custom string is also accepted (set `--hub-avatar-badge-color`).
 */
type HubAvatarBadgeColor = 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info' | 'light' | 'dark';
/**
 * Universal avatar component that
 * generates avatar from different sources
 *
 * export
 * class AvatarComponent
 * implements {OnChanges}
 */
declare class AvatarComponent implements AfterContentInit, OnChanges, OnDestroy {
    private sourceFactory;
    private avatarService;
    private sanitizer;
    readonly round: _angular_core.InputSignal<boolean>;
    readonly size: _angular_core.InputSignal<string | number>;
    readonly textSizeRatio: _angular_core.InputSignal<number>;
    readonly bgColor: _angular_core.InputSignal<string | undefined>;
    readonly fgColor: _angular_core.InputSignal<string>;
    readonly borderColor: _angular_core.InputSignal<string | undefined>;
    /**
     * When `true` (default) an initials avatar gets a background colour derived from
     * a hash of its `name`, applied inline. Set to `false` to suppress that inline
     * colour so the avatar can be themed via the `--hub-avatar-bg-color` CSS variable
     * without needing `!important`. An explicit `bgColor` always wins over both.
     */
    readonly autoColor: _angular_core.InputSignalWithTransform<boolean, unknown>;
    readonly style: _angular_core.InputSignal<Style>;
    readonly cornerRadius: _angular_core.InputSignal<string | number>;
    readonly facebook: _angular_core.InputSignal<string | null | undefined>;
    readonly gravatar: _angular_core.InputSignal<string | null | undefined>;
    readonly github: _angular_core.InputSignal<string | null | undefined>;
    readonly custom: _angular_core.InputSignal<string | SafeUrl | null | undefined>;
    readonly customAlt: _angular_core.InputSignal<string | null | undefined>;
    readonly initials: _angular_core.InputSignal<string | null | undefined>;
    readonly value: _angular_core.InputSignal<string | null | undefined>;
    readonly referrerpolicy: _angular_core.InputSignal<string | null | undefined>;
    readonly placeholder: _angular_core.InputSignal<string | undefined>;
    readonly initialsSize: _angular_core.InputSignal<string | number>;
    /**
     * Overlay badge at the bottom-end corner. A boolean / empty value renders a plain
     * dot (great for a presence indicator); a string or number renders a labelled badge
     * (e.g. a count like `"4k"`). `null` / absent (default) renders nothing.
     *
     * @example <hub-avatar badge badgeColor="success" />      // dot
     * @example <hub-avatar badge="4k" badgeColor="danger" />  // labelled
     */
    readonly badge: _angular_core.InputSignal<string | number | boolean | null>;
    /**
     * Semantic colour of the {@link badge} (and, as a host class, of the avatar itself).
     * Maps to a `--hub-sys-color-*` token; any custom string also works (set
     * `--hub-avatar-badge-color`). When unset the badge uses a neutral default.
     */
    readonly badgeColor: _angular_core.InputSignal<HubAvatarBadgeColor | (string & {}) | null>;
    /**
     * Normalises {@link badgeColor} into a paintable value for the `--hub-avatar-badge-color`
     * accent slot, accepting ANY colour. A bareword (a semantic name, a host-registered accent,
     * or a CSS named colour) resolves to its design-system token `var(--hub-sys-color-<name>,
     * <name>)` — the raw word is the fallback so an unregistered name still paints. A literal
     * `#hex` / `rgb()` / `oklch()` / `var(...)` is passed through unchanged. `null` when unset,
     * so the SCSS default (and the builtin `@each` per `data-badge-color`) takes over.
     */
    protected readonly badgeColorVar: _angular_core.Signal<string | null>;
    /** True when a badge should be rendered (the `badge` input is set to anything but `null` / `false`). */
    protected readonly _hasBadge: _angular_core.Signal<boolean>;
    /** The badge's text content; empty for a plain dot (`badge` is `true` or an empty string). */
    protected readonly _badgeText: _angular_core.Signal<string>;
    /** True when the badge is a plain dot (shown, but with no text content). */
    protected readonly _isDot: _angular_core.Signal<boolean>;
    readonly clickOnAvatar: _angular_core.OutputEmitterRef<Source>;
    /** Wrapper around the projected content (`<ng-content>`), used to detect whether the consumer projected anything. */
    private customContentRef?;
    /** True when the consumer projected custom content (an icon, SVG, image, …) into the avatar. */
    hasCustomContent: boolean;
    /** Inline style applied to the projected-content slot (honours `bgColor` / `fgColor` / `borderColor` / `style`). */
    customContentStyle: StyleObject;
    isAlive: boolean;
    avatarSrc: SafeUrl | null;
    avatarAlt: SafeUrl | null;
    avatarText: string | null;
    avatarStyle: StyleObject;
    hostStyle: StyleObject;
    private currentIndex;
    private sources;
    constructor(sourceFactory: SourceFactory, avatarService: AvatarService, sanitizer: DomSanitizer);
    onAvatarClicked(): void;
    /**
     * Detects projected content once it is available and, when present, computes its style.
     * Runs after content init so `<ng-content>` nodes are already in place.
     */
    ngAfterContentInit(): void;
    /**
     * Returns true when the projected slot holds a real element or non-whitespace text,
     * so whitespace-only projection does not flip the avatar into custom-content mode.
     *
     * @param host The element wrapping the projected content.
     */
    private hasMeaningfulProjectedContent;
    /**
     * Builds the inline style for the projected-content slot. Sensible visible defaults
     * (a themed background circle and a readable foreground colour) come from CSS tokens;
     * the `bgColor` / `fgColor` / `borderColor` / `style` inputs override them when set.
     */
    private getCustomContentStyle;
    /**
     * The avatar size as a px string. Exposed on the host as `--hub-avatar-size`
     * so the status dot (and any token-driven child) scales with the avatar.
     */
    get avatarSizePx(): string;
    /**
     * Detect inputs change
     *
     * param {{ [propKey: string]: SimpleChange }} changes
     *
     * memberof AvatarComponent
     */
    ngOnChanges(changes: SimpleChanges): void;
    /**
     * Fetch avatar source
     *
     * memberOf AvatarComponent
     */
    fetchAvatarSource(): void;
    private findNextSource;
    ngOnDestroy(): void;
    /**
     * Initialize the avatar component and its fallback system
     */
    private initializeAvatar;
    private sortAvatarSources;
    private buildTextAvatar;
    private buildImageAvatar;
    /**
     *
     * returns initials style
     *
     * memberOf AvatarComponent
     */
    private getInitialsStyle;
    /**
     *
     * returns image style
     *
     * memberOf AvatarComponent
     */
    private getImageStyle;
    private getCustomStyleObject;
    private parseInlineStyleString;
    /**
     * Fetch avatar image asynchronously.
     *
     * param {Source} source represents avatar source
     * memberof AvatarComponent
     */
    private fetchAndProcessAsyncAvatar;
    /**
     * Add avatar source
     *
     * param sourceType avatar source type e.g facebook,twitter, etc.
     * param sourceValue  source value e.g facebookId value, etc.
     */
    private addSource;
    /**
     * Remove avatar source
     *
     * param sourceType avatar source type e.g facebook,twitter, etc.
     */
    private removeSource;
    static ɵfac: _angular_core.ɵɵFactoryDeclaration<AvatarComponent, never>;
    static ɵcmp: _angular_core.ɵɵComponentDeclaration<AvatarComponent, "hub-avatar", never, { "round": { "alias": "round"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "textSizeRatio": { "alias": "textSizeRatio"; "required": false; "isSignal": true; }; "bgColor": { "alias": "bgColor"; "required": false; "isSignal": true; }; "fgColor": { "alias": "fgColor"; "required": false; "isSignal": true; }; "borderColor": { "alias": "borderColor"; "required": false; "isSignal": true; }; "autoColor": { "alias": "autoColor"; "required": false; "isSignal": true; }; "style": { "alias": "style"; "required": false; "isSignal": true; }; "cornerRadius": { "alias": "cornerRadius"; "required": false; "isSignal": true; }; "facebook": { "alias": "facebookId"; "required": false; "isSignal": true; }; "gravatar": { "alias": "gravatarId"; "required": false; "isSignal": true; }; "github": { "alias": "githubId"; "required": false; "isSignal": true; }; "custom": { "alias": "src"; "required": false; "isSignal": true; }; "customAlt": { "alias": "alt"; "required": false; "isSignal": true; }; "initials": { "alias": "name"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; "referrerpolicy": { "alias": "referrerpolicy"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "initialsSize": { "alias": "initialsSize"; "required": false; "isSignal": true; }; "badge": { "alias": "badge"; "required": false; "isSignal": true; }; "badgeColor": { "alias": "badgeColor"; "required": false; "isSignal": true; }; }, { "clickOnAvatar": "clickOnAvatar"; }, never, ["*"], true, never>;
}

/**
 * Backward-compatibility module for `<hub-avatar>`.
 *
 * @deprecated `AvatarComponent` is now a standalone component. Import it directly
 * (`imports: [AvatarComponent]`) and, if you need custom configuration, register
 * `provideAvatar()` in your application providers. This module only re-exports the
 * standalone component and will be removed in a future major version.
 */
declare class AvatarModule {
    /**
     * @deprecated Use `provideAvatar(config)` with the standalone APIs instead.
     * Kept so existing `AvatarModule.forRoot()` consumers keep working.
     */
    static forRoot(avatarConfig?: AvatarConfig): ModuleWithProviders<AvatarModule>;
    static ɵfac: _angular_core.ɵɵFactoryDeclaration<AvatarModule, never>;
    static ɵmod: _angular_core.ɵɵNgModuleDeclaration<AvatarModule, never, [typeof AvatarComponent], [typeof AvatarComponent]>;
    static ɵinj: _angular_core.ɵɵInjectorDeclaration<AvatarModule>;
}

/**
 * Registers the avatar configuration for standalone applications.
 *
 * Standalone-friendly replacement for `AvatarModule.forRoot()`. Add it to your
 * `bootstrapApplication` providers (or a route's `providers`) to customise the
 * avatar source priority, colour palette or src-cache behaviour. Calling it is
 * optional — `<hub-avatar>` works out of the box with sensible defaults.
 *
 * ```ts
 * import { provideAvatar } from 'ng-hub-ui-avatar';
 *
 * bootstrapApplication(AppComponent, {
 *   providers: [
 *     provideAvatar({ sourcePriorityOrder: [AvatarSource.GRAVATAR, AvatarSource.INITIALS] })
 *   ]
 * });
 * ```
 *
 * @param config Optional avatar configuration.
 * @returns Environment providers to add to the application config.
 */
declare function provideAvatar(config?: AvatarConfig): EnvironmentProviders;

export { AvatarComponent, AvatarModule, AvatarService, AvatarSource, defaultColors, defaultDisableSrcCache, defaultSources, provideAvatar };
export type { AvatarConfig, HubAvatarBadgeColor };