fix(code-block)!: errors following a full review of the component (#DS-5482)

docs/guides/migration.en.md

@@ -1035,7 +1035,7 @@ for each option it deselected and reporting the shortened value to the form cont
 
 ### 18. Component review (20.3.0)
 
-Ten components went through a full review in 20.3.0: notification-center, popover, search-expandable, select, split-button, title, toast, tooltip, tree and tree-select. Each review closed the members that were never part of the component's contract, moved inputs to signals where that was the point of it, and fixed the behavior it uncovered along the way. Only the changes that reach a consumer are listed here.
+Components went through a full review in 20.3.0, in two waves. The first covered notification-center, popover, search-expandable, select, split-button, title, toast, tooltip, tree and tree-select; the second is the one each subsection below belongs to. Each review closed the members that were never part of the component's contract, moved inputs to signals where that was the point of it, and fixed the behavior it uncovered along the way. Only the changes that reach a consumer are listed here.
 
 Every schematic named below runs automatically:
 
@@ -1049,6 +1049,32 @@ Most of them report rather than rewrite: what replaces a removed member or a sig
 ng g @koobiq/components:<schematic-name> --project <your project>
 ```
 
+#### Code block
+
+`maxHeight` was published as `InputSignal<number>` over an `undefined!` default, so a code block with no `[maxHeight]` binding reported `undefined` from a non-nullable type:
+
+```ts
+const height: number = codeBlock.maxHeight(); // held undefined
+if (codeBlock.maxHeight() > 0) { … }          // NaN comparison, never true
+```
+
+It reports `number | undefined` now. Nothing about the runtime value changed — the call sites that were quietly wrong now fail to compile.
+
+`KbqCodeBlockHighlight.file` was a write-only required input: a setter with no getter that kicked off highlighting as a side effect. It is a required signal input driven by an effect now, so it can finally be read — and a programmatic write no longer compiles.
+
+| Pattern                                  | Manual migration                                                    |
+| ---------------------------------------- | ------------------------------------------------------------------- |
+| `.maxHeight()`                           | `?? 0` for the common reading, or handle the unset state explicitly |
+| `.file = …` on a `KbqCodeBlockHighlight` | Bind `[file]`; the value is readable as `file()` now                |
+
+**The `max-height` applied while `viewAll` is off is a `computed`.** It was a getter read from a `[style.max-height.px]` binding, so it only re-evaluated when something else marked the view dirty.
+
+`softWrap`, `viewAll`, `canDownload`, `activeFileIndex` and `files` are backed by signals. They stay accessor inputs with the same types and the same two-way outputs — they are written by the component as well as by the binding, and a `model()` cannot carry the `booleanAttribute` / `numberAttribute` transform they need. No call site changes.
+
+**Shrinking `files` so that `activeFileIndex` equals the new length now resets the active file to 0.** The guard compared `files.length < activeFileIndex`, which left the first out-of-range index in place, and the block then rendered from an undefined file.
+
+Reported by `code-block-optional-max-height`.
+
 #### Search expandable
 
 Step 4 already renames the `kbq-filter-search` element to `kbq-search-expandable`. That rewrite only ever touched the tag, so the inputs of the removed `KbqFilterBarSearch` survived as attributes the new component does not have — silently, because an unknown attribute on a component is not an error. `v20-upgrade` renames them too now:

docs/guides/migration.ru.md

@@ -1039,7 +1039,7 @@ ng g @koobiq/components:list-tree-multiple-input --project <your project>
 
 ### 18. Ревью компонентов (20.3.0)
 
-В 20.3.0 полное ревью прошли десять компонентов: notification-center, popover, search-expandable, select, split-button, title, toast, tooltip, tree и tree-select. Каждое ревью закрывало члены, которые никогда не были частью контракта компонента, переводило входы на сигналы там, где в этом и был его смысл, и попутно исправляло найденные ошибки поведения. Ниже перечислено только то, что доходит до потребителя.
+В 20.3.0 полное ревью прошло в две волны. В первую вошли notification-center, popover, search-expandable, select, split-button, title, toast, tooltip, tree и tree-select; ко второй относится каждый из подразделов ниже. Каждое ревью закрывало члены, которые никогда не были частью контракта компонента, переводило входы на сигналы там, где в этом и был его смысл, и попутно исправляло найденные ошибки поведения. Ниже перечислено только то, что доходит до потребителя.
 
 Все схематики, названные ниже, запускаются автоматически:
 
@@ -1053,6 +1053,32 @@ ng update @koobiq/components@20
 ng g @koobiq/components:<schematic-name> --project <your project>
 ```
 
+#### Code block
+
+`maxHeight` был опубликован как `InputSignal<number>` поверх значения по умолчанию `undefined!`, поэтому блок кода без привязки `[maxHeight]` возвращал `undefined` из ненулевого типа:
+
+```ts
+const height: number = codeBlock.maxHeight(); // содержал undefined
+if (codeBlock.maxHeight() > 0) { … }          // сравнение с NaN, никогда не истинно
+```
+
+Теперь он возвращает `number | undefined`. В рантайме ничего не изменилось — просто места вызова, которые и так были неправильными, перестали компилироваться.
+
+`KbqCodeBlockHighlight.file` был входом только на запись: сеттер без геттера, который побочным эффектом запускал подсветку. Теперь это обязательный сигнальный вход, которым управляет `effect`, поэтому его наконец можно прочитать — а программная запись больше не компилируется.
+
+| Что было                              | Как мигрировать вручную                                              |
+| ------------------------------------- | -------------------------------------------------------------------- |
+| `.maxHeight()`                        | `?? 0` для обычного чтения либо явная обработка незаданного значения |
+| `.file = …` у `KbqCodeBlockHighlight` | Привязать `[file]`; значение теперь читается как `file()`            |
+
+**`max-height`, который применяется, пока `viewAll` выключен, стал `computed`.** Это был геттер, читаемый из привязки `[style.max-height.px]`, поэтому он пересчитывался только тогда, когда представление помечал грязным кто-то другой.
+
+`softWrap`, `viewAll`, `canDownload`, `activeFileIndex` и `files` теперь опираются на сигналы. Они остались входами на геттере и сеттере с теми же типами и теми же двусторонними событиями — в них пишет и сам компонент, и привязка, а `model()` не умеет нести нужную им трансформацию `booleanAttribute` / `numberAttribute`. Места вызова не меняются.
+
+**Если `files` укоротить так, что `activeFileIndex` станет равен новой длине, активный файл теперь сбрасывается на 0.** Проверка сравнивала `files.length < activeFileIndex` и оставляла первый выходящий за границы индекс, после чего блок показывал содержимое неопределённого файла.
+
+Сообщается схематиком `code-block-optional-max-height`.
+
 #### Search expandable
 
 Шаг 4 уже переименовывает элемент `kbq-filter-search` в `kbq-search-expandable`. Но та замена трогала только тег, поэтому входы удалённого `KbqFilterBarSearch` оставались в разметке атрибутами, которых у нового компонента нет, — и молча, потому что неизвестный атрибут на компоненте не является ошибкой. Теперь `v20-upgrade` переименовывает и их:

packages/components/code-block/code-block-highlight.ts

@@ -2,9 +2,9 @@ import { DOCUMENT } from '@angular/common';
 import {
     booleanAttribute,
     Directive,
+    effect,
     inject,
     InjectionToken,
-    Input,
     input,
     isDevMode,
     numberAttribute,
@@ -95,6 +95,7 @@ export class KbqCodeBlockHighlight {
     private readonly window = inject(KBQ_WINDOW);
     private readonly config = inject(KBQ_CODE_BLOCK_HIGHLIGHT_JS_CONFIG, { optional: true });
     private hljs: HLJSApi | null = null;
+    private hljsLoading: Promise<void> | null = null;
     private readonly _pending = signal(false);
 
     /**
@@ -105,17 +106,32 @@ export class KbqCodeBlockHighlight {
     readonly pending = this._pending.asReadonly();
 
     /** The code file. */
-    // TODO: Skipped for migration because:
-    //  Accessor inputs cannot be migrated as they are too complex.
-    @Input({ required: true })
-    set file(file: KbqCodeBlockFile) {
-        if (!this.window) return;
+    readonly file = input.required<KbqCodeBlockFile>();
 
-        if (!this.hljs) {
-            this.load(this.config ?? {}).then(() => this.highlight(file));
-        } else {
-            this.highlight(file);
-        }
+    constructor() {
+        effect((onCleanup) => {
+            const file = this.file();
+
+            if (!this.window) return;
+
+            if (this.hljs) {
+                this.highlight(file);
+
+                return;
+            }
+
+            // A `file` that arrives while highlight.js is still loading must not start a second load,
+            // and must not highlight through a directive that has gone away in the meantime.
+            let cancelled = false;
+
+            onCleanup(() => (cancelled = true));
+
+            this.loadOnce().then(() => {
+                if (!cancelled) {
+                    this.highlight(file);
+                }
+            });
+        });
     }
 
     /** The starting line number. */
@@ -124,6 +140,18 @@ export class KbqCodeBlockHighlight {
     /** Whether to display line numbers for single line code block. */
     readonly singleLine = input<boolean, unknown>(false, { transform: booleanAttribute });
 
+    /** Loads highlight.js at most once, so overlapping `file` changes share a single import. */
+    private loadOnce(): Promise<void> {
+        this.hljsLoading ??= this.load(this.config ?? {}).finally(() => {
+            if (!this.hljs) {
+                // The load failed; let a later file change try again rather than latching the failure.
+                this.hljsLoading = null;
+            }
+        });
+
+        return this.hljsLoading;
+    }
+
     private async load({ core, languages }: KbqCodeBlockHighlightJsConfig): Promise<void> {
         this._pending.set(true);
 

packages/components/code-block/code-block.html

@@ -102,7 +102,7 @@
     kbqOverflowShadowContainer
     kbqTabNavPanel
     class="kbq-code-block__main"
-    [style.max-height.px]="calculatedMaxHeight"
+    [style.max-height.px]="calculatedMaxHeight()"
     [tabIndex]="codeContentTabIndex"
 >
     <pre

packages/components/code-block/code-block.spec.ts

@@ -939,4 +939,81 @@ describe(KbqCodeBlock.name, () => {
             expect(scrollSpy).toHaveBeenCalledWith({ top: 100 });
         }));
     });
+    it('should report undefined for an unbound maxHeight', () => {
+        const fixture = createComponent(BaseCodeBlock);
+        const codeBlock = geCodeBlockDebugElement(fixture.debugElement).componentInstance as KbqCodeBlock;
+
+        fixture.detectChanges();
+
+        expect(codeBlock.maxHeight()).toBeUndefined();
+    });
+
+    it('should drop the calculated max height once viewAll is on', () => {
+        const fixture = createComponent(BaseCodeBlock);
+        const { componentInstance } = fixture;
+        const codeBlock = geCodeBlockDebugElement(fixture.debugElement).componentInstance as KbqCodeBlock;
+
+        componentInstance.maxHeight = 200;
+        fixture.detectChanges();
+
+        const main = fixture.nativeElement.querySelector('.kbq-code-block__main') as HTMLElement;
+
+        expect(codeBlock.maxHeight()).toBe(200);
+        expect(main.style.maxHeight).toBe('200px');
+
+        codeBlock.toggleViewAll();
+        fixture.detectChanges();
+
+        expect(main.style.maxHeight).toBe('');
+    });
+
+    it('should expose the highlighted file on the highlight directive', () => {
+        const fixture = createComponent(BaseCodeBlock);
+
+        fixture.detectChanges();
+
+        const highlight = fixture.debugElement
+            .query(By.directive(KbqCodeBlockHighlight))
+            .injector.get(KbqCodeBlockHighlight);
+
+        expect(highlight.file().filename).toBe('index.html');
+
+        fixture.componentInstance.activeFileIndex = 1;
+        fixture.detectChanges();
+
+        expect(highlight.file().filename).toBe('main.ts');
+    });
+    it('should follow a maxHeight that changes after init', () => {
+        const fixture = createComponent(BaseCodeBlock);
+        const { componentInstance } = fixture;
+
+        componentInstance.maxHeight = 200;
+        fixture.detectChanges();
+
+        const main = fixture.nativeElement.querySelector('.kbq-code-block__main') as HTMLElement;
+
+        expect(main.style.maxHeight).toBe('200px');
+
+        componentInstance.maxHeight = 400;
+        fixture.detectChanges();
+
+        expect(main.style.maxHeight).toBe('400px');
+    });
+
+    it('should reset the active file when it falls outside a shorter file list', () => {
+        const fixture = createComponent(BaseCodeBlock);
+        const { componentInstance } = fixture;
+        const codeBlock = geCodeBlockDebugElement(fixture.debugElement).componentInstance as KbqCodeBlock;
+
+        componentInstance.activeFileIndex = 2;
+        fixture.detectChanges();
+
+        expect(codeBlock.activeFileIndex).toBe(2);
+
+        // Two files leave 0 and 1 valid, so the index has to come back into range.
+        componentInstance.files = componentInstance.files.slice(0, 2);
+        fixture.detectChanges();
+
+        expect(codeBlock.activeFileIndex).toBe(0);
+    });
 });