@koobiq/components 20.4.1 → 21.0.0

package/types/koobiq-components-username.d.ts

@@ -0,0 +1,340 @@
+import * as i0 from '@angular/core';
+import { InjectionToken, Signal, Provider, PipeTransform } from '@angular/core';
+import * as _koobiq_components_core from '@koobiq/components/core';
+import { KbqUsernameLocaleConfiguration, KbqDeepPartial } from '@koobiq/components/core';
+
+/**
+ * Keys naming the profile field a format character stands for.
+ *
+ * The key identifies the *field* only. Whether it renders in full or as an initial is decided by the
+ * pipe that reads the format: `KbqUsernamePipe` abbreviates a key that is followed by {@link Dot},
+ * `KbqUsernameCustomPipe` abbreviates the lowercase keys. The two upper/lower pairs therefore exist so
+ * that a single mapping serves both rules.
+ */
+declare enum KbqUsernameFormatKey {
+    /** First name, abbreviated by `KbqUsernameCustomPipe`. */
+    FirstNameShort = "f",
+    /** First name, rendered in full by `KbqUsernameCustomPipe`. */
+    FirstNameFull = "F",
+    /** Middle name, abbreviated by `KbqUsernameCustomPipe`. */
+    MiddleNameShort = "m",
+    /** Middle name, rendered in full by `KbqUsernameCustomPipe`. */
+    MiddleNameFull = "M",
+    /** Last name, abbreviated by `KbqUsernameCustomPipe`. */
+    LastNameShort = "l",
+    /** Last name, rendered in full by `KbqUsernameCustomPipe`. */
+    LastNameFull = "L",
+    /** Abbreviation mark. `KbqUsernamePipe` abbreviates the key it follows; never maps to a field. */
+    Dot = "."
+}
+/**
+ * Maps each format key to a property name in the user profile object.
+ * Allows flexible formatting regardless of profile field names.
+ *
+ * Excludes the uppercase keys: `KbqUsernamePipe` decides shortness from a following
+ * {@link KbqUsernameFormatKey.Dot}, so a case pair would carry no meaning for it. The mapping that does
+ * carry them is {@link KbqFormatKeyToProfileMappingExtended}.
+ */
+type KbqFormatKeyToProfileMapping<T = any> = {
+    [key in Exclude<KbqUsernameFormatKey, KbqUsernameFormatKey.FirstNameFull | KbqUsernameFormatKey.MiddleNameFull | KbqUsernameFormatKey.LastNameFull>]: keyof T | undefined;
+};
+/**
+ * Maps each format key to a property name in the user profile object.
+ * Allows flexible formatting regardless of profile field names.
+ *
+ * Covers the uppercase keys as well, which is the pair {@link KbqUsernameCustomPipe} derives the form from.
+ */
+type KbqFormatKeyToProfileMappingExtended<T = any> = {
+    [key in KbqUsernameFormatKey]: keyof T | undefined;
+};
+/** Basic user info rendered by `kbq-username`. */
+type KbqUserInfo = {
+    /** Given name. */
+    firstName?: string;
+    /** Family name. */
+    lastName?: string;
+    /** Middle name or patronymic. */
+    middleName?: string;
+    /** Account name, rendered as the secondary part. */
+    login?: string;
+    /** Site the account belongs to, rendered in parentheses after the login. */
+    site?: string;
+};
+/**
+ * Layout mode for displaying a username and applying text-ellipsis.
+ *
+ * - `stacked`: Elements shown vertically.
+ * - `inline`: Elements shown in one line. Text ellipsis is applied to both parts.
+ * - `text`: `display: inline`, so the username flows inside a sentence; nothing clips it, hence no title.
+ */
+type KbqUsernameMode = 'stacked' | 'inline' | 'text';
+/**
+ * Visual style of the username.
+ *
+ * - `default`: standard styling with primary and secondary colors.
+ * - `error`: error colors (e.g., red).
+ * - `accented`: no color theming; emphasizes via typography only.
+ * - `inherit`: inherits parent styles, no theming. For example, useful when using inside links.
+ */
+type KbqUsernameStyle = 'default' | 'error' | 'accented' | 'inherit';
+
+/**
+ * Default format of `KbqUsernameCustomPipe`: full last name, first and middle names as initials.
+ *
+ * Written in that pipe's own syntax — uppercase keys render the full value, lowercase ones an initial,
+ * and every other character is copied verbatim, which is where the spaces and the dots come from.
+ */
+declare const kbqDefaultFullNameFormatCustom = "L f. m.";
+/**
+ * Default format of `KbqUsernamePipe` and of the `kbq-username` component: full last name, first and
+ * middle names as initials.
+ *
+ * Written in that pipe's own syntax — a key followed by `.` renders an initial, any other key renders
+ * the full value, and the separating spaces are inserted by the pipe rather than by the format.
+ */
+declare const kbqDefaultFullNameFormat = "lf.m.";
+/**
+ * Mapping of every format key onto a field of {@link KbqUserInfo}. Backs {@link KBQ_PROFILE_MAPPING}
+ * and is the fallback of both pipes, so a profile shaped like `KbqUserInfo` needs no mapping at all.
+ *
+ * Covers the uppercase keys as well, which is what makes `kbqDefaultFullNameFormatCustom` work out of
+ * the box; spread it to map extra fields without losing the defaults.
+ */
+declare const kbqDefaultProfileMapping: {
+    f: "firstName";
+    F: "firstName";
+    m: "middleName";
+    M: "middleName";
+    l: "lastName";
+    L: "lastName";
+    ".": undefined;
+};
+/**
+ * Injection token for providing a global username format-to-profile mapping.
+ *
+ * Resolved where the `kbq-username` component or the pipe lives, so a component-level or route-level
+ * provider applies to that subtree. Outside a template, resolve it from your own injection context —
+ * `kbqInjectUsernameFormatter()` does exactly that.
+ */
+declare const KBQ_PROFILE_MAPPING: InjectionToken<KbqFormatKeyToProfileMapping | KbqFormatKeyToProfileMappingExtended>;
+/** Default localized strings of `kbq-username`. */
+declare const KBQ_USERNAME_DEFAULT_LOCALE_CONFIGURATION: KbqUsernameLocaleConfiguration;
+/** Localization configuration provider for `kbq-username`. */
+declare const KBQ_USERNAME_LOCALE_CONFIGURATION: InjectionToken<KbqUsernameLocaleConfiguration>;
+/**
+ * Utility provider. Only the strings you pass are overridden; the rest keep following the active locale.
+ *
+ * Provides {@link KBQ_USERNAME_LOCALE_CONFIGURATION}.
+ */
+declare const kbqUsernameLocaleConfigurationProvider: (configuration: KbqDeepPartial<KbqUsernameLocaleConfiguration>) => Provider;
+/**
+ * Injection function that creates a reactive locale configuration signal for `kbq-username`.
+ *
+ * @docs-private
+ */
+declare function kbqInjectUsernameLocaleConfiguration(): Signal<KbqUsernameLocaleConfiguration>;
+
+/** Styles the primary part of the username (e.g. full name). */
+declare class KbqUsernamePrimary {
+    static ɵfac: i0.ɵɵFactoryDeclaration<KbqUsernamePrimary, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<KbqUsernamePrimary, "[kbqUsernamePrimary]", ["kbqUsernamePrimary"], {}, {}, never, never, true, never>;
+}
+/** Styles the secondary part. */
+declare class KbqUsernameSecondary {
+    static ɵfac: i0.ɵɵFactoryDeclaration<KbqUsernameSecondary, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<KbqUsernameSecondary, "[kbqUsernameSecondary]", ["kbqUsernameSecondary"], {}, {}, never, never, true, never>;
+}
+/** Styles a secondary hint. */
+declare class KbqUsernameSecondaryHint {
+    static ɵfac: i0.ɵɵFactoryDeclaration<KbqUsernameSecondaryHint, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<KbqUsernameSecondaryHint, "[kbqUsernameSecondaryHint]", ["kbqUsernameSecondaryHint"], {}, {}, never, never, true, never>;
+}
+/** Custom content for `KbqUsername`, overrides default view. */
+declare class KbqUsernameCustomView {
+    static ɵfac: i0.ɵɵFactoryDeclaration<KbqUsernameCustomView, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<KbqUsernameCustomView, "kbq-username-custom-view, [kbq-username-custom-view]", ["kbqUsernameCustomView"], {}, {}, never, never, true, never>;
+}
+/**
+ * Displays a user's name based on profile data.
+ * Supports different display modes and visual styles.
+ * A custom view can be provided via `<kbq-username-custom-view>` for full control over the output.
+ * Accepts input profile data and optional formatting options.
+ */
+declare class KbqUsername {
+    /**
+     * Resolved at the component's own injector, so a mapping scoped to a route or a host component
+     * applies to what is rendered here.
+     */
+    private readonly mapping;
+    /** User profile data used for display. */
+    readonly userInfo: i0.InputSignal<KbqUserInfo | undefined>;
+    /** Enables compact display mode */
+    readonly isCompact: i0.InputSignalWithTransform<boolean, unknown>;
+    /** Format string for rendering the user's full name. */
+    readonly fullNameFormat: i0.InputSignal<string>;
+    /**
+     * Display mode of the username. Defaults to `'inline'`.
+     */
+    readonly mode: i0.InputSignal<KbqUsernameMode>;
+    /**
+     * Visual style of the username. Defaults to `'default'`.
+     */
+    readonly type: i0.InputSignal<KbqUsernameStyle>;
+    /**
+     * Custom projected view for username rendering.
+     *
+     * @docs-private
+     */
+    protected readonly customView: i0.Signal<KbqUsernameCustomView | undefined>;
+    /** @docs-private */
+    protected readonly localeConfiguration: i0.Signal<_koobiq_components_core.KbqUsernameLocaleConfiguration>;
+    /**
+     * Name as rendered, i.e. abbreviated according to `fullNameFormat`.
+     *
+     * @docs-private
+     */
+    protected readonly formattedName: i0.Signal<string>;
+    /**
+     * Whether the profile yields any name at all. A profile carrying only one of the name fields still
+     * has a name, and the formatter degrades to whatever it finds.
+     *
+     * @docs-private
+     */
+    protected readonly hasName: i0.Signal<boolean>;
+    /**
+     * Unabbreviated name, offered as the tooltip of the truncated primary part.
+     *
+     * @docs-private
+     */
+    protected readonly expandedName: i0.Signal<string>;
+    /**
+     * Tooltip of the secondary part: the login with the site hint it renders inline.
+     *
+     * @docs-private
+     */
+    protected readonly secondaryTitle: i0.Signal<string>;
+    /**
+     * Tooltip of the compact layout, whose single part carries the name — or the login when there is
+     * none — followed by the site.
+     *
+     * @docs-private
+     */
+    protected readonly compactTitle: i0.Signal<string>;
+    /**
+     * Whether the layout can clip its text. `kbq-truncate-line()` is applied to `stacked` and `inline`
+     * only, so in `text` mode nothing is ever clipped and the verdict `kbq-title` computes is known in
+     * advance. Attaching it there would cost a `MutationObserver` per part and a forced layout read on
+     * every resize and every content mutation, for a tooltip that could never show.
+     *
+     * @docs-private
+     */
+    protected readonly canTruncate: i0.Signal<boolean>;
+    /** @docs-private */
+    protected readonly class: i0.Signal<string>;
+    private withSite;
+    static ɵfac: i0.ɵɵFactoryDeclaration<KbqUsername, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<KbqUsername, "kbq-username", ["kbqUsername"], { "userInfo": { "alias": "userInfo"; "required": false; "isSignal": true; }; "isCompact": { "alias": "isCompact"; "required": false; "isSignal": true; }; "fullNameFormat": { "alias": "fullNameFormat"; "required": false; "isSignal": true; }; "mode": { "alias": "mode"; "required": false; "isSignal": true; }; "type": { "alias": "type"; "required": false; "isSignal": true; }; }, {}, ["customView"], ["kbq-username-custom-view,[kbq-username-custom-view]"], true, never>;
+}
+
+/**
+ * Formats a profile the way `KbqUsernamePipe` and `kbq-username` do: a key followed by
+ * {@link KbqUsernameFormatKey.Dot} renders an initial, any other key renders the full value, and the
+ * parts are joined with single spaces — a character that is neither a mapped key nor `.` is dropped.
+ *
+ * Fields the profile does not carry are skipped one by one, so a partial profile still renders whatever
+ * it has.
+ *
+ * @param profile Profile to format. Anything that is not a record — null, a primitive, an array —
+ * formats as an empty string.
+ * @param format Format string, e.g. {@link kbqDefaultFullNameFormat}.
+ * @param mapping Format key to profile field mapping, e.g. {@link kbqDefaultProfileMapping}. Resolve it
+ * from your own injection context — `inject(KBQ_PROFILE_MAPPING)` — to honour a scoped override.
+ */
+declare function kbqFormatUsername<T = unknown>(profile: T, format: string, mapping: KbqFormatKeyToProfileMapping | KbqFormatKeyToProfileMappingExtended): string;
+/**
+ * Formats a profile the way `KbqUsernameCustomPipe` does: a lowercase key renders an initial, an
+ * uppercase one the full value, and every character with no mapped field — the separators — is emitted
+ * verbatim, which is what lets the format carry its own punctuation.
+ *
+ * @param profile Profile to format. Anything that is not a record — null, a primitive, an array —
+ * formats as an empty string.
+ * @param format Format string, e.g. {@link kbqDefaultFullNameFormatCustom}.
+ * @param mapping Format key to profile field mapping, e.g. {@link kbqDefaultProfileMapping}. Resolve it
+ * from your own injection context — `inject(KBQ_PROFILE_MAPPING)` — to honour a scoped override.
+ */
+declare function kbqFormatUsernameCustom<T = unknown>(profile: T, format: string, mapping: KbqFormatKeyToProfileMapping | KbqFormatKeyToProfileMappingExtended): string;
+/**
+ * Formats a user profile into a name string.
+ *
+ * A key followed by `.` renders an initial and any other key renders the full value; the separating
+ * spaces are inserted by the pipe, so a character that is neither a mapped key nor `.` is dropped.
+ *
+ * {@link KbqUsernameCustomPipe} derives the form from the key's case instead, and keeps the format's own
+ * punctuation.
+ */
+declare class KbqUsernamePipe<T = unknown> implements PipeTransform {
+    private readonly mapping;
+    /** Builds a formatted name string from the user profile using the provided format and mapping. */
+    transform(profile: T, format?: string, customMapping?: KbqFormatKeyToProfileMapping): string;
+    static ɵfac: i0.ɵɵFactoryDeclaration<KbqUsernamePipe<any>, never>;
+    static ɵpipe: i0.ɵɵPipeDeclaration<KbqUsernamePipe<any>, "kbqUsername", true>;
+}
+/**
+ * Formats a user profile into a name string.
+ *
+ * A lowercase key renders an initial and an uppercase one the full value; every character with no
+ * mapped field is emitted verbatim, so the format carries its own separators.
+ *
+ * {@link KbqUsernamePipe} derives the form from a following `.` instead.
+ */
+declare class KbqUsernameCustomPipe<T = unknown> implements PipeTransform {
+    private readonly mapping;
+    /** Builds a formatted name string from the user profile using the provided format and mapping. */
+    transform(profile: T, format?: string, customMapping?: KbqFormatKeyToProfileMappingExtended<T>): string;
+    static ɵfac: i0.ɵɵFactoryDeclaration<KbqUsernameCustomPipe<any>, never>;
+    static ɵpipe: i0.ɵɵPipeDeclaration<KbqUsernameCustomPipe<any>, "kbqUsernameCustom", true>;
+}
+/**
+ * Returns the formatter `kbq-username` renders with, bound to the `KBQ_PROFILE_MAPPING` visible at the
+ * call site. Use it wherever the displayed string is needed outside a template — a search filter, an
+ * option label — so that a scoped mapping applies to both paths.
+ *
+ * Must run in an injection context.
+ */
+declare function kbqInjectUsernameFormatter(): <T>(profile: T, format?: string) => string;
+interface KbqUsernameTextOptions {
+    /** Formats the login segment. Defaults to identity. */
+    formatLogin?: (login: string) => string;
+    /**
+     * Formats the site segment.
+     * Defaults to wrapping in parentheses, matching kbq-username display.
+     */
+    formatSite?: (site: string) => string;
+    /**
+     * Wraps every segment in `U+2068`/`U+2069` so that a right-to-left name keeps its order next to a
+     * left-to-right login, and the parentheses around the site stay attached to it.
+     *
+     * Off by default: the isolates are invisible but real characters, and this string is commonly fed to
+     * an `includes()` filter that would stop matching.
+     */
+    bidiIsolate?: boolean;
+}
+/**
+ * Builds a full username string from a pre-formatted name plus optional login and site,
+ * mirroring the text rendered by `kbq-username`.
+ *
+ * Provide custom `formatLogin` / `formatSite` to tailor the output.
+ */
+declare function kbqBuildUsernameText(data: {
+    name: string;
+} & Partial<Pick<KbqUserInfo, 'login' | 'site'>>, options?: KbqUsernameTextOptions): string;
+
+/** Exports every `kbq-username` building block: the component, the styling directives and both pipes. */
+declare class KbqUsernameModule {
+    static ɵfac: i0.ɵɵFactoryDeclaration<KbqUsernameModule, never>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<KbqUsernameModule, never, [typeof KbqUsername, typeof KbqUsernameCustomView, typeof KbqUsernamePrimary, typeof KbqUsernameSecondary, typeof KbqUsernameSecondaryHint, typeof KbqUsernameCustomPipe, typeof KbqUsernamePipe], [typeof KbqUsername, typeof KbqUsernameCustomView, typeof KbqUsernamePrimary, typeof KbqUsernameSecondary, typeof KbqUsernameSecondaryHint, typeof KbqUsernameCustomPipe, typeof KbqUsernamePipe]>;
+    static ɵinj: i0.ɵɵInjectorDeclaration<KbqUsernameModule>;
+}
+
+export { KBQ_PROFILE_MAPPING, KBQ_USERNAME_DEFAULT_LOCALE_CONFIGURATION, KBQ_USERNAME_LOCALE_CONFIGURATION, KbqUsername, KbqUsernameCustomPipe, KbqUsernameCustomView, KbqUsernameFormatKey, KbqUsernameModule, KbqUsernamePipe, KbqUsernamePrimary, KbqUsernameSecondary, KbqUsernameSecondaryHint, kbqBuildUsernameText, kbqDefaultFullNameFormat, kbqDefaultFullNameFormatCustom, kbqDefaultProfileMapping, kbqFormatUsername, kbqFormatUsernameCustom, kbqInjectUsernameFormatter, kbqInjectUsernameLocaleConfiguration, kbqUsernameLocaleConfigurationProvider };
+export type { KbqFormatKeyToProfileMapping, KbqFormatKeyToProfileMappingExtended, KbqUserInfo, KbqUsernameMode, KbqUsernameStyle, KbqUsernameTextOptions };

package/username/_username-theme.scss

@@ -0,0 +1,35 @@
+@mixin kbq-username-theme() {
+    & {
+        color: var(--kbq-username-primary-color);
+
+        .kbq-username__secondary,
+        .kbq-username__secondary-hint {
+            color: var(--kbq-username-secondary-color);
+        }
+    }
+
+    // Both parts carry the secondary color on their own: the primary part is rendered only when the
+    // profile has a name, so keying the color on an adjacent primary sibling left a login-only profile,
+    // and every custom view that reorders the parts, in the primary color.
+    &.kbq-username_default {
+        .kbq-username__secondary,
+        .kbq-username__secondary-hint {
+            --kbq-username-secondary-color: var(--kbq-foreground-contrast-secondary);
+        }
+    }
+
+    &.kbq-username_error {
+        --kbq-username-primary-color: var(--kbq-foreground-error);
+        --kbq-username-secondary-color: var(--kbq-foreground-error);
+    }
+
+    &.kbq-username_accented {
+        --kbq-username-primary-color: var(--kbq-foreground-contrast);
+        --kbq-username-secondary-color: var(--kbq-foreground-contrast);
+    }
+
+    &.kbq-username_inherit {
+        --kbq-username-primary-color: inherit;
+        --kbq-username-secondary-color: inherit;
+    }
+}

package/username/username.scss

@@ -1,5 +1,6 @@
 @use '../core/styles/common';
 @use '../core/styles/common/tokens';
+@use './username-theme' as *;
 
 // Targets the layout container: either the root or custom view if present.
 @mixin _kbq-username-content-wrapper {
@@ -9,39 +10,6 @@
     }
 }
 
-@mixin _kbq-username-theme() {
-    & {
-        color: var(--kbq-username-primary-color);
-
-        .kbq-username__secondary,
-        .kbq-username__secondary-hint {
-            color: var(--kbq-username-secondary-color);
-        }
-    }
-
-    &.kbq-username_default {
-        .kbq-username__secondary-hint,
-        .kbq-username__primary + .kbq-username__secondary {
-            --kbq-username-secondary-color: var(--kbq-foreground-contrast-secondary);
-        }
-    }
-
-    &.kbq-username_error {
-        --kbq-username-primary-color: var(--kbq-foreground-error);
-        --kbq-username-secondary-color: var(--kbq-foreground-error);
-    }
-
-    &.kbq-username_accented {
-        --kbq-username-primary-color: var(--kbq-foreground-contrast);
-        --kbq-username-secondary-color: var(--kbq-foreground-contrast);
-    }
-
-    &.kbq-username_inherit {
-        --kbq-username-primary-color: inherit;
-        --kbq-username-secondary-color: inherit;
-    }
-}
-
 @mixin _kbq-username-typography() {
     & {
         @include tokens.kbq-typography-level-to-styles_css-variables(typography, text-normal);
@@ -55,9 +23,17 @@
 }
 
 .kbq-username {
-    @include _kbq-username-theme();
+    @include kbq-username-theme();
     @include _kbq-username-typography();
 
+    // Each part is its own directional run, so a right-to-left name next to a left-to-right login keeps
+    // the intended order and the parentheses around the site hint stay attached to it.
+    .kbq-username__primary,
+    .kbq-username__secondary,
+    .kbq-username__secondary-hint {
+        unicode-bidi: isolate;
+    }
+
     &.kbq-username_stacked {
         @include _kbq-username-content-wrapper {
             display: flex;