feat(username): init component (#DS-3296)

.github/CODEOWNERS

@@ -34,6 +34,7 @@
 /packages/components/timezone/*                             @NikGurev
 /packages/components/toggle/*                               @NikGurev
 /packages/components/top-bar/*                              @NikGurev
+/packages/components/username/*                             @NikGurev
 
 /packages/components/actions-panel/*                        @artembelik
 /packages/components/autocomplete/*                         @artembelik

angular.json

@@ -2368,6 +2368,36 @@
                 }
             }
         },
+        "dev-username": {
+            "projectType": "application",
+            "root": "packages/components-dev/username",
+            "sourceRoot": "packages/components-dev/username",
+            "architect": {
+                "build": {
+                    "builder": "@angular-devkit/build-angular:application",
+                    "options": {
+                        "outputPath": {
+                            "base": "dist/components-dev/username"
+                        },
+                        "tsConfig": "packages/components-dev/username/tsconfig.app.json",
+                        "index": "packages/components-dev/index.html",
+                        "styles": ["packages/components-dev/main.scss"],
+                        "polyfills": ["zone.js"],
+                        "extractLicenses": false,
+                        "sourceMap": true,
+                        "optimization": false,
+                        "namedChunks": true,
+                        "browser": "packages/components-dev/username/main.ts"
+                    }
+                },
+                "serve": {
+                    "builder": "@angular-devkit/build-angular:dev-server",
+                    "options": {
+                        "buildTarget": "dev-username:build"
+                    }
+                }
+            }
+        },
         "dev-validation": {
             "projectType": "application",
             "root": "packages/components-dev/validation",

apps/docs/src/app/services/documentation-items.ts

@@ -793,6 +793,17 @@ const DOCS: { [key: string]: DocsDocCategory[] } = {
                     hasApi: true,
                     apiId: 'tree-select',
                     hasExamples: true
+                },
+                {
+                    id: 'username',
+                    name: {
+                        ru: 'Username',
+                        en: 'Username'
+                    },
+                    hasApi: true,
+                    apiId: 'username',
+                    hasExamples: false,
+                    isNew: expiresAt('2025-08-24')
                 }
             ]
         }

apps/docs/src/sitemap.xml

@@ -720,6 +720,18 @@
 	<url>
 		<loc>https://koobiq.io/ru/components/tree-select/api</loc>
 	</url>
+	<url>
+		<loc>https://koobiq.io/en/components/username/overview</loc>
+	</url>
+	<url>
+		<loc>https://koobiq.io/ru/components/username/overview</loc>
+	</url>
+	<url>
+		<loc>https://koobiq.io/en/components/username/api</loc>
+	</url>
+	<url>
+		<loc>https://koobiq.io/ru/components/username/api</loc>
+	</url>
 	<url>
 		<loc>https://koobiq.io/en/other/date-formatter/overview</loc>
 	</url>

package.json

@@ -264,6 +264,7 @@
         "dev:tree": "ng serve dev-tree --port 3003",
         "dev:tree-select": "ng serve dev-tree-select --port 3003",
         "dev:typography": "ng serve dev-typography --port 3003",
+        "dev:username": "ng serve dev-username --port 3003",
         "dev:validation": "ng serve dev-validation --port 3003",
         "dev:z-index": "ng serve dev-z-index --port 3003",
         "-----UNIT_TESTS-----": "-------------------------------------------------------------------------------------",

packages/components-dev/username/main.ts

@@ -0,0 +1,9 @@
+import { bootstrapApplication } from '@angular/platform-browser';
+import { provideAnimations } from '@angular/platform-browser/animations';
+import { DevApp } from './module';
+
+bootstrapApplication(DevApp, {
+    providers: [
+        provideAnimations()
+    ]
+}).catch((error) => console.error(error));

packages/components-dev/username/module.ts

@@ -0,0 +1,40 @@
+import { ChangeDetectionStrategy, Component, ViewEncapsulation } from '@angular/core';
+import { UsernameExamplesModule } from '../../docs-examples/components/username';
+
+@Component({
+    selector: 'dev-examples',
+    standalone: true,
+    imports: [UsernameExamplesModule],
+    template: `
+        <username-overview-example />
+        <username-playground-example />
+        <username-custom-example />
+        <username-as-link-example />
+    `,
+    styles: `
+        :host {
+            display: flex;
+            gap: var(--kbq-size-l);
+            flex-wrap: wrap;
+        }
+        :host > * {
+            border-radius: var(--kbq-size-border-radius);
+            border: 1px solid var(--kbq-line-contrast-less);
+            margin-bottom: var(--kbq-size-l);
+            padding: var(--kbq-size-m);
+            flex: 1 0 auto;
+        }
+    `,
+    changeDetection: ChangeDetectionStrategy.OnPush
+})
+class DevExamples {}
+
+@Component({
+    selector: 'dev-app',
+    standalone: true,
+    imports: [DevExamples],
+    templateUrl: './template.html',
+    encapsulation: ViewEncapsulation.None,
+    changeDetection: ChangeDetectionStrategy.OnPush
+})
+export class DevApp {}

packages/components-dev/username/template.html

@@ -0,0 +1 @@
+<dev-examples />

packages/components-dev/username/tsconfig.app.json

@@ -0,0 +1,5 @@
+{
+    "extends": "../tsconfig.json",
+    "include": ["**/*.d.ts"],
+    "files": ["main.ts"]
+}

packages/components/username/__snapshots__/username.spec.ts.snap

@@ -0,0 +1,20 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`KbqUsername should use default input values 1`] = `
+{
+  "kbq-username": true,
+  "kbq-username_default": true,
+  "kbq-username_inline": true,
+}
+`;
+
+exports[`KbqUsernamePipe should format full name using custom format 1`] = `
+[
+  "Alice B C",
+  "Alice B. C.",
+  "AliceB.C.",
+  "A B C",
+  "A.B.C.",
+  "Alice B. C.",
+]
+`;

packages/components/username/constants.ts

@@ -0,0 +1,30 @@
+import { InjectionToken } from '@angular/core';
+import { KbqFormatKeyToProfileMapping, KbqFormatKeyToProfileMappingExtended, KbqUsernameFormatKey } from './types';
+
+/** Default name format: Last name full, first and middle as initials. */
+export const kbqDefaultFullNameFormatCustom = 'L f. m.';
+/** Default name format: Last name full, first and middle as initials. */
+export const kbqDefaultFullNameFormat = 'lf.m.';
+
+/**
+ * Throws an error when no profile field mapping is provided to the username pipe.
+ * @docs-private
+ */
+export function KbqMappingMissingError() {
+    return new Error('KbqUsernamePipe: profile field mapping is required but was not provided.');
+}
+
+/**
+ * Injection token for providing a global username format-to-profile mapping.
+ */
+export const KBQ_PROFILE_MAPPING = new InjectionToken<
+    KbqFormatKeyToProfileMapping | KbqFormatKeyToProfileMappingExtended
+>('KBQ_PROFILE_MAPPING', {
+    factory: () =>
+        ({
+            [KbqUsernameFormatKey.FirstNameShort]: 'firstName',
+            [KbqUsernameFormatKey.MiddleNameShort]: 'middleName',
+            [KbqUsernameFormatKey.LastNameShort]: 'lastName',
+            [KbqUsernameFormatKey.Dot]: undefined
+        }) satisfies KbqFormatKeyToProfileMapping<{ firstName: string; middleName: string; lastName: string }>
+});

packages/components/username/index.ts

@@ -0,0 +1,5 @@
+export * from './constants';
+export * from './module';
+export * from './types';
+export * from './username';
+export * from './username.pipe';

packages/components/username/module.ts

@@ -0,0 +1,18 @@
+import { NgModule } from '@angular/core';
+import { KbqUsername, KbqUsernameCustomView, KbqUsernamePrimary, KbqUsernameSecondary } from './username';
+import { KbqUsernameCustomPipe, KbqUsernamePipe } from './username.pipe';
+
+const COMPONENTS = [
+    KbqUsername,
+    KbqUsernameCustomView,
+    KbqUsernamePrimary,
+    KbqUsernameSecondary,
+    KbqUsernameCustomPipe,
+    KbqUsernamePipe
+];
+
+@NgModule({
+    imports: COMPONENTS,
+    exports: COMPONENTS
+})
+export class KbqUsernameModule {}

packages/components/username/ng-package.json

@@ -0,0 +1,5 @@
+{
+    "lib": {
+        "entryFile": "index.ts"
+    }
+}

packages/components/username/types.ts

@@ -0,0 +1,74 @@
+/**
+ * Keys for formatting username parts in short (initial) or full form.
+ */
+export enum KbqUsernameFormatKey {
+    /**
+     * Short form of the first name (e.g., "John" → "J")
+     */
+    FirstNameShort = 'f',
+
+    /**
+     * Full form of the first name (e.g., "John")
+     */
+    FirstNameFull = 'F',
+
+    /**
+     * Short form of the middle name (e.g., "Henry" → "H")
+     */
+    MiddleNameShort = 'm',
+
+    /**
+     * Full form of the middle name (e.g., "Henry")
+     */
+    MiddleNameFull = 'M',
+
+    /**
+     * Short form of the last name (e.g., "Doe" → "D")
+     */
+    LastNameShort = 'l',
+
+    /**
+     * Full form of the last name (e.g., "Doe")
+     */
+    LastNameFull = 'L',
+    Dot = '.'
+}
+
+/**
+ * Maps each format key to a property name in the user profile object.
+ * Allows flexible formatting regardless of profile field names.
+ */
+export 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.
+ * @see KbqUsernameCustomPipe
+ */
+export type KbqFormatKeyToProfileMappingExtended<T = any> = {
+    [key in KbqUsernameFormatKey]: keyof T | undefined;
+};
+
+/**
+ * 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`: Plain text, no layout styling. No text-ellipsis.
+ */
+export 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.
+ */
+export type KbqUsernameStyle = 'default' | 'error' | 'accented' | 'inherit';

packages/components/username/username-tokens.scss

@@ -0,0 +1,6 @@
+:where(.kbq-username) {
+    --kbq-username-primary-color: var(--kbq-foreground-contrast);
+    --kbq-username-secondary-color: inherit;
+    --kbq-username-vertical-gap: var(--kbq-size-xxs);
+    --kbq-username-horizontal-gap: var(--kbq-size-xxs);
+}

packages/components/username/username.en.md

@@ -0,0 +1,23 @@
+The pattern is used when the interface refers to an internal user.
+
+Displaying the username means showing a set of attributes from the internal system user that help identify them in the interface.
+
+<!-- example(username-overview) -->
+
+### Configuration demo
+
+<!-- example(username-playground) -->
+
+### Custom template
+
+If flexible layout is required and the default template doesn’t meet your needs, use the `custom` mode with the `KbqUsernameCustomView` directive.
+
+This mode supports the same display styles and modes while maintaining consistency with the design system.
+
+To format the full name, use the `kbqUsernameCustom` pipe with a format string and a mapping definition (an object that links format elements to corresponding user properties, determining what data should be shown).
+
+<!-- example(username-custom) -->
+
+The component can be conveniently used inside links. To visually match the link style, set the `inherit` style — this ensures that color and appearance are inherited from the parent element.
+
+<!-- example(username-as-link) -->

packages/components/username/username.html

@@ -0,0 +1,35 @@
+@let profile = userInfo();
+<ng-content select="kbq-username-custom-view,[kbq-username-custom-view]" />
+
+@if (!customView() && profile) {
+    @let fullName = profile | kbqUsername: fullNameFormat();
+
+    @if (!isCompact()) {
+        @if (hasFullName()) {
+            <span kbq-title kbqUsernamePrimary>{{ fullName }}</span>
+        }
+
+        @if (profile.login) {
+            <span kbq-title kbqUsernameSecondary>
+                {{ profile.login }}
+
+                @if (profile.site) {
+                    <span kbqUsernameSecondaryHint>({{ profile.site }})</span>
+                }
+            </span>
+        }
+    } @else {
+        <span kbq-title kbqUsernamePrimary>
+            @if (hasFullName()) {
+                <span>{{ fullName }}</span>
+            }
+            @if (!hasFullName() && profile.login) {
+                {{ profile.login }}
+            }
+
+            @if (profile.site) {
+                <span kbqUsernameSecondaryHint>&nbsp;({{ profile.site }})</span>
+            }
+        </span>
+    }
+}