From 3befaf5e41998e5dd400cce5e37897a8ab770b41 Mon Sep 17 00:00:00 2001
From: lskramarov <l.s.kramarov@gmail.com>
Date: Wed, 17 Jun 2026 18:20:09 +0300
Subject: [PATCH] chore(icon): add icon adoptedStyleSheets @layer demo in dev
 (#DS-5207)

---
 angular.json                                  |  37 ++++
 package.json                                  |   1 +
 .../icon-adopted-stylesheets/global.scss      |  38 ++++
 .../icon-adopted-stylesheets/main.ts          |   9 +
 .../icon-adopted-stylesheets/module.ts        | 119 ++++++++++++
 .../icon-adopted-stylesheets/styles.scss      |  86 ++++++++
 .../icon-adopted-stylesheets/template.html    | 183 ++++++++++++++++++
 .../tsconfig.app.json                         |   5 +
 8 files changed, 478 insertions(+)
 create mode 100644 packages/components-dev/icon-adopted-stylesheets/global.scss
 create mode 100644 packages/components-dev/icon-adopted-stylesheets/main.ts
 create mode 100644 packages/components-dev/icon-adopted-stylesheets/module.ts
 create mode 100644 packages/components-dev/icon-adopted-stylesheets/styles.scss
 create mode 100644 packages/components-dev/icon-adopted-stylesheets/template.html
 create mode 100644 packages/components-dev/icon-adopted-stylesheets/tsconfig.app.json

diff --git a/angular.json b/angular.json
index 84d5f216ba..6685f4282a 100644
--- a/angular.json
+++ b/angular.json
@@ -594,6 +594,43 @@
                 }
             }
         },
+        "dev-icon-adopted-stylesheets": {
+            "projectType": "application",
+            "root": "packages/components-dev/icon-adopted-stylesheets",
+            "sourceRoot": "packages/components-dev/icon-adopted-stylesheets",
+            "architect": {
+                "build": {
+                    "builder": "@angular-devkit/build-angular:application",
+                    "options": {
+                        "outputPath": {
+                            "base": "dist/components-dev/icon-adopted-stylesheets"
+                        },
+                        "tsConfig": "packages/components-dev/icon-adopted-stylesheets/tsconfig.app.json",
+                        "index": "packages/components-dev/index.html",
+                        "styles": ["packages/components-dev/icon-adopted-stylesheets/global.scss"],
+                        "assets": [
+                            {
+                                "glob": "**/*",
+                                "input": "node_modules/@koobiq/icons/fonts",
+                                "output": "assets/kbq-icons"
+                            }
+                        ],
+                        "polyfills": ["zone.js"],
+                        "extractLicenses": false,
+                        "sourceMap": true,
+                        "optimization": false,
+                        "namedChunks": true,
+                        "browser": "packages/components-dev/icon-adopted-stylesheets/main.ts"
+                    }
+                },
+                "serve": {
+                    "builder": "@angular-devkit/build-angular:dev-server",
+                    "options": {
+                        "buildTarget": "dev-icon-adopted-stylesheets:build"
+                    }
+                }
+            }
+        },
         "dev-button-toggle": {
             "projectType": "application",
             "root": "packages/components-dev/button-toggle",
diff --git a/package.json b/package.json
index fa04bf8ef8..28a65ed8d3 100644
--- a/package.json
+++ b/package.json
@@ -222,6 +222,7 @@
         "dev:highlight": "ng serve dev-highlight --port 3003",
         "dev:hint": "ng serve dev-hint --port 3003",
         "dev:icon": "ng serve dev-icon --port 3003",
+        "dev:icon-adopted-stylesheets": "ng serve dev-icon-adopted-stylesheets --port 3003",
         "dev:icon-item": "ng serve dev-icon-item --port 3003",
         "dev:inline-edit": "ng serve dev-inline-edit --port 3003",
         "dev:input": "ng serve dev-input --port 3003",
diff --git a/packages/components-dev/icon-adopted-stylesheets/global.scss b/packages/components-dev/icon-adopted-stylesheets/global.scss
new file mode 100644
index 0000000000..a162d270ec
--- /dev/null
+++ b/packages/components-dev/icon-adopted-stylesheets/global.scss
@@ -0,0 +1,38 @@
+// Copy of packages/components-dev/main.scss WITHOUT the `@use '@koobiq/icons/fonts/kbq-icons'` line.
+// The base icon CSS is intentionally NOT loaded as an author <style> — it is delivered at runtime
+// via adoptedStyleSheets/<style> (see module.ts) to reproduce the bug and verify the fix.
+
+@use '@koobiq/design-tokens/web/new/css-tokens.css';
+@use '@koobiq/design-tokens/web/new/css-tokens-light.css';
+@use '@koobiq/design-tokens/web/new/css-tokens-dark.css';
+
+@use '../../components/core/styles/theming/prebuilt/theme';
+@use '../../components/core/styles/visual/layout';
+@use '../../components/core/styles/common/list';
+@use '../../components/core/styles/common/tokens';
+
+// Inter
+@import '@fontsource/inter/400.css';
+@import '@fontsource/inter/500.css';
+@import '@fontsource/inter/600.css';
+@import '@fontsource/inter/700.css';
+@import '@fontsource/inter/400-italic.css';
+@import '@fontsource/inter/500-italic.css';
+
+// JetBrains Mono
+@import '@fontsource/jetbrains-mono/400.css';
+@import '@fontsource/jetbrains-mono/700.css';
+
+@include layout.layouts-for-breakpoint();
+
+body {
+    @include tokens.kbq-typography-level-to-styles-css-variables(typography, text-normal);
+
+    background: var(--kbq-background-bg);
+    color: var(--kbq-foreground-contrast);
+    margin: 0;
+}
+
+hr {
+    margin: var(--kbq-size-xxl) 0;
+}
diff --git a/packages/components-dev/icon-adopted-stylesheets/main.ts b/packages/components-dev/icon-adopted-stylesheets/main.ts
new file mode 100644
index 0000000000..2bbc80baf3
--- /dev/null
+++ b/packages/components-dev/icon-adopted-stylesheets/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));
diff --git a/packages/components-dev/icon-adopted-stylesheets/module.ts b/packages/components-dev/icon-adopted-stylesheets/module.ts
new file mode 100644
index 0000000000..6f311aa479
--- /dev/null
+++ b/packages/components-dev/icon-adopted-stylesheets/module.ts
@@ -0,0 +1,119 @@
+import { DOCUMENT } from '@angular/common';
+import {
+    ChangeDetectionStrategy,
+    Component,
+    inject,
+    OnDestroy,
+    OnInit,
+    signal,
+    ViewEncapsulation
+} from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { KbqBadgeColors, KbqBadgeModule } from '@koobiq/components/badge';
+import { KbqButtonModule } from '@koobiq/components/button';
+import { KbqComponentColors } from '@koobiq/components/core';
+import { KbqFormFieldModule } from '@koobiq/components/form-field';
+import { KbqIconModule } from '@koobiq/components/icon';
+import { KbqInputModule } from '@koobiq/components/input';
+import { KbqLinkModule } from '@koobiq/components/link';
+import { KbqTagsModule } from '@koobiq/components/tags';
+import { DevThemeToggle } from '../theme-toggle';
+
+/** How the base icon CSS is delivered into the this.document. */
+type IconMode = 'style' | 'adopted' | 'adopted-layer';
+
+@Component({
+    selector: 'dev-app',
+    imports: [
+        FormsModule,
+        KbqIconModule,
+        KbqButtonModule,
+        KbqBadgeModule,
+        KbqLinkModule,
+        KbqTagsModule,
+        KbqFormFieldModule,
+        KbqInputModule,
+        DevThemeToggle
+    ],
+    templateUrl: './template.html',
+    styleUrls: ['./styles.scss'],
+    changeDetection: ChangeDetectionStrategy.OnPush,
+    encapsulation: ViewEncapsulation.None
+})
+export class DevApp implements OnInit, OnDestroy {
+    private readonly document = inject(DOCUMENT);
+
+    readonly colors = KbqComponentColors;
+    readonly badgeColors = KbqBadgeColors;
+
+    /** Non-empty value so that kbq-password-toggle is visible (it is hidden when the control is empty). */
+    password = 'Secret123!';
+
+    /** Current icon CSS delivery mode. Defaults to `adopted` (no layer) so the bug is visible right away. */
+    readonly mode = signal<IconMode>('adopted');
+
+    /** kbq-icons.css text with its url() rewritten to the served asset path. */
+    private css = '';
+    private readonly sheet = new CSSStyleSheet();
+    private styleEl?: HTMLStyleElement;
+
+    ngOnInit(): void {
+        void this.loadCss();
+    }
+
+    private async loadCss(): Promise<void> {
+        const raw = await fetch('assets/kbq-icons/kbq-icons.css').then((response) => response.text());
+
+        // Both <style> and adopted sheets resolve url() against the document base URL,
+        // so rewrite the relative './kbq-icons.(ttf|woff)' to the served asset path.
+        this.css = raw.replaceAll('url("./', 'url("assets/kbq-icons/');
+
+        this.apply(this.mode());
+    }
+
+    ngOnDestroy(): void {
+        this.detach();
+    }
+
+    apply(mode: IconMode): void {
+        this.mode.set(mode);
+        this.detach();
+
+        if (!this.css) {
+            return;
+        }
+
+        switch (mode) {
+            // Baseline "as today": an author <style> at the start of <head> comes earlier in the cascade
+            // than component styles, so same-specificity overrides (rotate helpers, etc.) win.
+            case 'style': {
+                const element = this.document.createElement('style');
+
+                element.textContent = this.css;
+                this.document.head.prepend(element);
+                this.styleEl = element;
+                break;
+            }
+            // Bug: adopted sheets sort AFTER all author styles → the base `.kbq` (0-1-0) beats the
+            // `.kbq-icon-rotate_*`/`.kbq-icon-flip-*` helpers (also 0-1-0) → rotations/flips are lost.
+            case 'adopted': {
+                this.sheet.replaceSync(this.css);
+                this.document.adoptedStyleSheets = [...this.document.adoptedStyleSheets, this.sheet];
+                break;
+            }
+            // Fix: a layered rule loses to any unlayered author rule of the same origin BEFORE
+            // specificity and order are compared → component overrides win again.
+            case 'adopted-layer': {
+                this.sheet.replaceSync(`@layer kbq-icons {\n${this.css}\n}`);
+                this.document.adoptedStyleSheets = [...this.document.adoptedStyleSheets, this.sheet];
+                break;
+            }
+        }
+    }
+
+    private detach(): void {
+        this.document.adoptedStyleSheets = this.document.adoptedStyleSheets.filter((sheet) => sheet !== this.sheet);
+        this.styleEl?.remove();
+        this.styleEl = undefined;
+    }
+}
diff --git a/packages/components-dev/icon-adopted-stylesheets/styles.scss b/packages/components-dev/icon-adopted-stylesheets/styles.scss
new file mode 100644
index 0000000000..b7ce59ce9c
--- /dev/null
+++ b/packages/components-dev/icon-adopted-stylesheets/styles.scss
@@ -0,0 +1,86 @@
+.dev-toolbar {
+    position: sticky;
+    top: 0;
+    z-index: 10;
+
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--kbq-size-l);
+
+    padding: var(--kbq-size-m);
+    margin-bottom: var(--kbq-size-l);
+
+    background: var(--kbq-background-bg);
+    border-bottom: 1px solid var(--kbq-line-contrast-less);
+}
+
+.dev-toolbar__modes {
+    display: flex;
+    gap: var(--kbq-size-s);
+    flex-wrap: wrap;
+}
+
+.dev-hint {
+    max-width: 920px;
+    margin: 0 var(--kbq-size-m) var(--kbq-size-xl);
+    padding: var(--kbq-size-m);
+
+    background: var(--kbq-background-theme-fade);
+    border-radius: var(--kbq-size-s);
+
+    code {
+        padding: 0 var(--kbq-size-3xs);
+        background: var(--kbq-background-contrast-fade);
+        border-radius: var(--kbq-size-3xs);
+    }
+}
+
+h3 {
+    margin: var(--kbq-size-xl) var(--kbq-size-m) var(--kbq-size-xs);
+}
+
+.dev-section-note {
+    margin: 0 var(--kbq-size-m) var(--kbq-size-m);
+    color: var(--kbq-foreground-contrast-secondary);
+}
+
+.dev-grid {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--kbq-size-l);
+
+    padding: var(--kbq-size-m);
+    margin: 0 var(--kbq-size-m);
+}
+
+.dev-grid_column {
+    flex-direction: column;
+    align-items: flex-start;
+}
+
+.dev-grid_baseline {
+    align-items: baseline;
+}
+
+.dev-cell {
+    display: inline-flex;
+    flex-direction: column;
+    align-items: center;
+    gap: var(--kbq-size-xxs);
+
+    min-width: 64px;
+    padding: var(--kbq-size-s);
+
+    border: 1px dashed var(--kbq-line-contrast-less);
+    border-radius: var(--kbq-size-xs);
+
+    small {
+        color: var(--kbq-foreground-contrast-secondary);
+    }
+}
+
+kbq-tag-list {
+    margin: 0 var(--kbq-size-m);
+}
diff --git a/packages/components-dev/icon-adopted-stylesheets/template.html b/packages/components-dev/icon-adopted-stylesheets/template.html
new file mode 100644
index 0000000000..ce5a366029
--- /dev/null
+++ b/packages/components-dev/icon-adopted-stylesheets/template.html
@@ -0,0 +1,183 @@
+<div class="dev-toolbar">
+    <div class="dev-toolbar__modes">
+        <button kbq-button [color]="mode() === 'style' ? colors.Theme : colors.ContrastFade" (click)="apply('style')">
+            &lt;style&gt; — эталон
+        </button>
+        <button
+            kbq-button
+            [color]="mode() === 'adopted' ? colors.Error : colors.ContrastFade"
+            (click)="apply('adopted')"
+        >
+            adoptedStyleSheets без слоя — БАГ
+        </button>
+        <button
+            kbq-button
+            [color]="mode() === 'adopted-layer' ? colors.Success : colors.ContrastFade"
+            (click)="apply('adopted-layer')"
+        >
+            adoptedStyleSheets + &#64;layer — ФИКС
+        </button>
+    </div>
+
+    <dev-theme-toggle />
+</div>
+
+<div class="dev-hint">
+    <b>Текущий режим: {{ mode() }}</b>
+    <div>
+        База шрифта иконок
+        <code>.kbq &#123; transform: rotate(0.001deg) &#125;</code>
+        (специфичность 0-1-0) конкурирует с хелперами иконки
+        <code>.kbq-icon-rotate_*</code>
+        /
+        <code>.kbq-icon-flip-*</code>
+        (тоже 0-1-0). В режиме
+        <b>adoptedStyleSheets без слоя</b>
+        база сортируется в каскаде последней и побеждает — повороты и флипы пропадают. Обёртка в
+        <code>&#64;layer kbq-icons</code>
+        возвращает приоритет переопределениям компонентов.
+    </div>
+</div>
+
+<h3>1. Повороты и флипы — наглядный баг</h3>
+<p class="dev-section-note">
+    Хелперы из
+    <code>icon.scss</code>
+    . В режиме «БАГ» иконки распрямляются в 0°; в «ФИКС» и «эталон» — повёрнуты.
+</p>
+<div class="dev-grid">
+    <span class="dev-cell">
+        <i kbq-icon="kbq-chevron-down-s_16"></i>
+        <small>без класса (0°)</small>
+    </span>
+    <span class="dev-cell">
+        <i kbq-icon="kbq-chevron-down-s_16" class="kbq-icon-rotate_90"></i>
+        <small>rotate_90</small>
+    </span>
+    <span class="dev-cell">
+        <i kbq-icon="kbq-chevron-down-s_16" class="kbq-icon-rotate_180"></i>
+        <small>rotate_180</small>
+    </span>
+    <span class="dev-cell">
+        <i kbq-icon="kbq-chevron-down-s_16" class="kbq-icon-rotate_270"></i>
+        <small>rotate_270</small>
+    </span>
+    <span class="dev-cell">
+        <i kbq-icon="kbq-north-east_16" class="kbq-icon-flip-h"></i>
+        <small>flip-h</small>
+    </span>
+    <span class="dev-cell">
+        <i kbq-icon="kbq-north-east_16" class="kbq-icon-flip-v"></i>
+        <small>flip-v</small>
+    </span>
+    <span class="dev-cell">
+        <i kbq-icon="kbq-north-east_16" class="kbq-icon-flip-vh"></i>
+        <small>flip-vh</small>
+    </span>
+</div>
+
+<h3>2. Input с password toggle — смещение иконки</h3>
+<p class="dev-section-note">
+    Иконка-глаз (
+    <code>kbq-password-toggle</code>
+    , это
+    <code>kbq-icon-button</code>
+    ) в суффиксе поля. В режиме «БАГ» база
+    <code>.kbq</code>
+    ломает выравнивание — глаз уезжает по вертикали; в «ФИКС»/«эталон» — на месте.
+</p>
+<div class="dev-grid dev-grid_column">
+    <kbq-form-field style="width: 280px">
+        <input kbqInputPassword placeholder="Пароль" [(ngModel)]="password" />
+        <kbq-password-toggle [kbqTooltipHidden]="'Показать пароль'" [kbqTooltipNotHidden]="'Скрыть пароль'" />
+    </kbq-form-field>
+</div>
+
+<h3>3. Кнопки с иконками</h3>
+<div class="dev-grid">
+    <button kbq-button>
+        <i kbq-icon="kbq-play_16"></i>
+        Слева
+    </button>
+    <button kbq-button>
+        Справа
+        <i kbq-icon="kbq-chevron-down-s_16"></i>
+    </button>
+    <button kbq-button>
+        <i kbq-icon="kbq-play_16"></i>
+        Обе
+        <i kbq-icon="kbq-chevron-down-s_16"></i>
+    </button>
+    <button kbq-button [color]="colors.Theme">
+        <i kbq-icon="kbq-magnifying-glass_16"></i>
+        Поиск
+    </button>
+</div>
+
+<h3>4. Бейджи с иконками</h3>
+<div class="dev-grid">
+    <kbq-badge [badgeColor]="badgeColors.FadeTheme">
+        <i kbq-icon="kbq-play_16"></i>
+        Новый
+    </kbq-badge>
+    <kbq-badge [badgeColor]="badgeColors.FadeSuccess">
+        Готово
+        <i kbq-icon="kbq-play_16"></i>
+    </kbq-badge>
+    <kbq-badge [badgeColor]="badgeColors.FadeError" [compact]="true">
+        <i kbq-icon="kbq-play_16"></i>
+        Ошибка
+    </kbq-badge>
+</div>
+
+<h3>5. Ссылки с иконками</h3>
+<div class="dev-grid dev-grid_column">
+    <a kbq-link href="https://koobiq.io">
+        <i kbq-icon="kbq-clock_16"></i>
+        <span class="kbq-link__text">Ссылка с ведущей иконкой</span>
+    </a>
+    <a kbq-link target="_blank" class="kbq-link_external" href="https://koobiq.io">
+        <span class="kbq-link__text">Внешняя ссылка</span>
+        <i kbq-icon="kbq-north-east_16"></i>
+    </a>
+</div>
+
+<h3>6. Теги с иконками</h3>
+<kbq-tag-list>
+    <kbq-tag value="search">
+        <i kbq-icon="kbq-magnifying-glass_16"></i>
+        с иконкой
+        <i kbq-icon="kbq-xmark-s_16" kbqTagRemove></i>
+    </kbq-tag>
+    <kbq-tag value="plain">
+        обычный
+        <i kbq-icon="kbq-xmark-s_16" kbqTagRemove></i>
+    </kbq-tag>
+</kbq-tag-list>
+
+<h3>7. icon-item</h3>
+<div class="dev-grid">
+    <i kbq-icon-item="kbq-folder-open_16" [color]="colors.Theme"></i>
+    <i kbq-icon-item="kbq-calendar-o_16" [color]="colors.Contrast"></i>
+    <i kbq-icon-item="kbq-clock_16" [color]="colors.Error"></i>
+    <i kbq-icon-item="kbq-folder-open_16" [big]="true" [color]="colors.Success"></i>
+</div>
+
+<h3>8. Голые иконки разных размеров</h3>
+<div class="dev-grid dev-grid_baseline">
+    <span class="dev-cell">
+        текст
+        <i kbq-icon="kbq-play_16"></i>
+        <small>16</small>
+    </span>
+    <span class="dev-cell">
+        текст
+        <i kbq-icon="kbq-calendar-o_16"></i>
+        <small>16</small>
+    </span>
+    <span class="dev-cell">
+        текст
+        <i kbq-icon="kbq-clock_16"></i>
+        <small>16</small>
+    </span>
+</div>
diff --git a/packages/components-dev/icon-adopted-stylesheets/tsconfig.app.json b/packages/components-dev/icon-adopted-stylesheets/tsconfig.app.json
new file mode 100644
index 0000000000..81fb90e7cb
--- /dev/null
+++ b/packages/components-dev/icon-adopted-stylesheets/tsconfig.app.json
@@ -0,0 +1,5 @@
+{
+    "extends": "../tsconfig.json",
+    "include": ["**/*.d.ts"],
+    "files": ["main.ts"]
+}