Merge pull request #9963 from ever-co/develop

release(stage): Documents hub main-thread wedge fix (facet option recreation)

Author: evereq

packages/plugins/docs-ui/src/lib/components/filter-bar/docs-filter-bar.component.ts

@@ -44,32 +44,57 @@ export class DocsFilterBarComponent extends TranslationBaseComponent {
 	}
 
 	// ─── Facet buckets (fall back to full enums when facets are unloaded) ───
+	//
+	// 🛑 These are consumed as `[buckets]="kindBuckets"` template bindings, which Angular
+	// re-evaluates on EVERY change-detection cycle. They must therefore return a STABLE array
+	// reference while `facets` is unchanged — a fresh `Object.values(...).map(...)` each cycle
+	// fed the downstream `<nb-select>`/`FacetMultiselectComponent` a new identity every tick,
+	// which recreated its `<nb-option>` children and self-retriggered change detection (the
+	// Documents-hub main-thread wedge). The cache below is keyed on the `facets` INPUT REFERENCE:
+	// the parent (browse page) replaces `facets` wholesale on each load, so identity equality is
+	// the correct and cheap invalidation signal.
+
+	private bucketsCache: { source: IDocumentFacets | null; buckets: Record<string, IDocumentFacetBucket[]> } = {
+		source: undefined as unknown as IDocumentFacets | null,
+		buckets: {}
+	};
+
+	private facetBuckets(key: string, compute: () => IDocumentFacetBucket[]): IDocumentFacetBucket[] {
+		if (this.bucketsCache.source !== this.facets) {
+			this.bucketsCache = { source: this.facets, buckets: {} };
+		}
+		return (this.bucketsCache.buckets[key] ??= compute());
+	}
 
 	get kindBuckets(): IDocumentFacetBucket[] {
-		return this.bucketsOrEnum(this.facets?.kind, Object.values(DocumentKindEnum));
+		return this.facetBuckets('kind', () => this.bucketsOrEnum(this.facets?.kind, Object.values(DocumentKindEnum)));
 	}
 
 	get statusBuckets(): IDocumentFacetBucket[] {
 		// UPLOADED folds into PROCESSING — filters offer only READY/PROCESSING/FAILED,
 		// and the Processing count carries the still-UPLOADED rows with it (R-STA-02).
 		const values = [DocumentStatusEnum.READY, DocumentStatusEnum.PROCESSING, DocumentStatusEnum.FAILED];
-		return this.bucketsOrEnum(foldStatusFacetBuckets(this.facets?.status), values);
+		return this.facetBuckets('status', () => this.bucketsOrEnum(foldStatusFacetBuckets(this.facets?.status), values));
 	}
 
 	get knowledgeBuckets(): IDocumentFacetBucket[] {
-		return this.bucketsOrEnum(this.facets?.knowledgeStatus, Object.values(DocumentKnowledgeStatusEnum));
+		return this.facetBuckets('knowledge', () =>
+			this.bucketsOrEnum(this.facets?.knowledgeStatus, Object.values(DocumentKnowledgeStatusEnum))
+		);
 	}
 
 	get sourceBuckets(): IDocumentFacetBucket[] {
-		return this.bucketsOrEnum(this.facets?.source, Object.values(DocumentSourceEnum));
+		return this.facetBuckets('source', () =>
+			this.bucketsOrEnum(this.facets?.source, Object.values(DocumentSourceEnum))
+		);
 	}
 
 	get categoryBuckets(): IDocumentFacetBucket[] {
-		return this.facets?.categories ?? [];
+		return this.facetBuckets('categories', () => this.facets?.categories ?? []);
 	}
 
 	get tagBuckets(): IDocumentFacetBucket[] {
-		return this.facets?.tags ?? [];
+		return this.facetBuckets('tags', () => this.facets?.tags ?? []);
 	}
 
 	kindLabel = (value: string): string => this.getTranslation(`DOCS.KIND.${value}`);

packages/plugins/docs-ui/src/lib/components/filter-bar/facet-multiselect.component.ts

@@ -16,7 +16,7 @@ import { IDocumentFacetBucket } from '../../models/docs-api.model';
 			[selected]="selected"
 			(selectedChange)="onSelectedChange($event)"
 		>
-			<nb-option *ngFor="let option of options" [value]="option.value">
+			<nb-option *ngFor="let option of options; trackBy: trackByValue" [value]="option.value">
 				{{ option.label }}
 				<span class="docs-facet-count" *ngIf="option.count !== undefined">({{ option.count }})</span>
 			</nb-option>
@@ -46,20 +46,51 @@ export class FacetMultiselectComponent implements OnChanges {
 
 	public options: { value: string; label: string; count?: number }[] = [];
 
+	/** Content fingerprint of the last-built `options`, so a same-content rebuild is skipped. */
+	private optionsSignature = '';
+
+	/**
+	 * 🛑 `options` MUST keep a STABLE reference across change-detection cycles whose content has
+	 * not changed. The filter bar binds `[buckets]` to getters (`get kindBuckets()` …) that return
+	 * a NEW array of NEW objects on every evaluation, and `[selected]="value?.kind || []"` mints a
+	 * fresh `[]` every cycle — so `ngOnChanges` fires on essentially every change detection. If we
+	 * rebuilt `options` unconditionally, `*ngFor` (even with `trackBy`) would receive a new array
+	 * each cycle; combined with `<nb-select>` re-querying its `<nb-option>` ContentChildren, that
+	 * recreated every option, whose `ngAfterViewInit` + the resulting content-query change
+	 * retriggered change detection — a self-sustaining loop that pegged the main thread on the
+	 * Documents hub (silent, zero HTTP, before the list even loaded). Rebuilding only when the
+	 * fingerprint changes keeps the reference stable and breaks the cycle; `trackByValue` is the
+	 * second line of defense for when the content genuinely does change.
+	 */
 	ngOnChanges(): void {
 		const buckets = this.buckets ?? [];
+		const selected = this.selected ?? [];
 		const known = new Set(buckets.map((bucket) => bucket.value));
-		this.options = buckets.map((bucket) => ({
-			value: bucket.value,
-			label: this.resolveLabel(bucket.value, bucket.label),
-			count: bucket.count
-		}));
-		// Keep stale selected values visible as appended options.
-		for (const value of this.selected ?? []) {
-			if (!known.has(value)) {
-				this.options.push({ value, label: this.resolveLabel(value) });
-			}
+		const stale = selected.filter((value) => !known.has(value));
+
+		const signature = JSON.stringify([
+			buckets.map((bucket) => [bucket.value, bucket.label, bucket.count]),
+			stale
+		]);
+		if (signature === this.optionsSignature) {
+			return;
 		}
+		this.optionsSignature = signature;
+
+		this.options = [
+			...buckets.map((bucket) => ({
+				value: bucket.value,
+				label: this.resolveLabel(bucket.value, bucket.label),
+				count: bucket.count
+			})),
+			// Keep stale selected values (deep links) visible as appended options.
+			...stale.map((value) => ({ value, label: this.resolveLabel(value) }))
+		];
+	}
+
+	/** Stable identity for `*ngFor` so unchanged options are never destroyed/recreated. */
+	trackByValue(_index: number, option: { value: string }): string {
+		return option.value;
 	}
 
 	onSelectedChange(values: string[]): void {

packages/plugins/docs-ui/src/lib/components/filter-bar/facet-multiselect.spec.ts

@@ -0,0 +1,83 @@
+import { FacetMultiselectComponent } from './facet-multiselect.component';
+import { IDocumentFacetBucket } from '../../models/docs-api.model';
+
+/**
+ * 🛑 Regression guard for the Documents-hub main-thread wedge.
+ *
+ * The filter bar binds `[buckets]` to getters and `[selected]="value?.x || []"`, both of which
+ * yield a NEW array identity on every change-detection cycle. `FacetMultiselectComponent` used to
+ * rebuild `options` (new array + new objects) on every resulting `ngOnChanges`, and its
+ * `*ngFor` had no `trackBy` — so `<nb-select>` recreated every `<nb-option>` each cycle, whose
+ * `ngAfterViewInit` + the content-query change retriggered change detection. That self-sustaining
+ * loop pegged the main thread the moment the hub rendered (silent, zero HTTP).
+ *
+ * The load-bearing invariant is: **when the bucket/selection CONTENT is unchanged, `options` keeps
+ * the same array reference across `ngOnChanges` calls** — even when the inputs are new arrays.
+ */
+describe('FacetMultiselectComponent — option reference stability', () => {
+	const bucket = (value: string, count?: number, label?: string): IDocumentFacetBucket =>
+		({ value, count, label } as IDocumentFacetBucket);
+
+	let component: FacetMultiselectComponent;
+
+	beforeEach(() => {
+		component = new FacetMultiselectComponent();
+	});
+
+	/** Feed inputs the way the template does: a brand-new array identity every cycle. */
+	const applyInputs = (values: string[], selected: string[] = []): void => {
+		component.buckets = values.map((v) => bucket(v, 1));
+		component.selected = [...selected];
+		component.ngOnChanges();
+	};
+
+	it('keeps the SAME options reference when the content has not changed across cycles', () => {
+		applyInputs(['FOLDER', 'PAGE', 'FILE']);
+		const first = component.options;
+
+		// Three more cycles with fresh input identities but identical content.
+		applyInputs(['FOLDER', 'PAGE', 'FILE']);
+		applyInputs(['FOLDER', 'PAGE', 'FILE']);
+		applyInputs(['FOLDER', 'PAGE', 'FILE']);
+
+		expect(component.options).toBe(first);
+	});
+
+	it('rebuilds options (new reference) only when the content actually changes', () => {
+		applyInputs(['FOLDER', 'PAGE']);
+		const first = component.options;
+
+		applyInputs(['FOLDER', 'PAGE', 'FILE']); // a real change
+		const second = component.options;
+
+		expect(second).not.toBe(first);
+		expect(second.map((o) => o.value)).toEqual(['FOLDER', 'PAGE', 'FILE']);
+	});
+
+	it('treats a changed count as a content change (facet counts arriving from the API)', () => {
+		component.buckets = [bucket('READY', undefined)];
+		component.selected = [];
+		component.ngOnChanges();
+		const before = component.options;
+
+		component.buckets = [bucket('READY', 12)];
+		component.ngOnChanges();
+
+		expect(component.options).not.toBe(before);
+		expect(component.options[0].count).toBe(12);
+	});
+
+	it('appends stale selected values as options and stays stable while they persist', () => {
+		applyInputs(['FOLDER'], ['ARCHIVED_KIND_NOT_IN_BUCKETS']);
+		const first = component.options;
+
+		expect(first.map((o) => o.value)).toEqual(['FOLDER', 'ARCHIVED_KIND_NOT_IN_BUCKETS']);
+
+		applyInputs(['FOLDER'], ['ARCHIVED_KIND_NOT_IN_BUCKETS']);
+		expect(component.options).toBe(first);
+	});
+
+	it('exposes a value-based trackBy so unchanged options are never recreated', () => {
+		expect(component.trackByValue(0, { value: 'FILE' })).toBe('FILE');
+	});
+});