Port #1350 to dtq-dev-9-base: UFAL/Backport #1333: admin-sidebar gutter via CSS var (no logged-in reload shift) (#1512)

For an authenticated user a hard reload shifted the whole page right by the
admin-sidebar width. The `.outer-wrapper` left gutter was produced by the
`@slideSidebarPadding` animation, whose width comes from `CSSVariableService`,
a browser-only store fed from `document.styleSheets`. On the server that store
is empty, so SSR emitted `style="padding-left: 0;"` and the browser resolved the
real width afterwards - hence the jump. Measured on dev-6 before this change:

  <div _ngcontent-... class="outer-wrapper ng-tns-c4194216939-0 ng-trigger
       ng-trigger-slideSidebarPadding" style="padding-left: 0;">

The gutter now comes from a CSS class - `ds-admin-sidebar-{hidden,unpinned,pinned}`,
derived from a small `sidebarPaddingState$` - whose `padding-left` resolves from
the `--ds-admin-sidebar-*` custom properties. Those are defined in the
render-blocking theme stylesheet (`--ds-admin-sidebar-fixed-element-width: 55px`,
`--ds-admin-sidebar-total-width: 305px` on dev-6), so CSS resolves the gutter
identically on the server and in the browser, with no hardcoded width and no
browser-only variable read. The pin/unpin slide is preserved by
`transition: padding-left 300ms`, gated behind `ds-admin-sidebar-animate`, which
`ngAfterViewInit` enables only after the first paint so the initial SSR->CSR
resolution never animates.

Adaptations to the v9 base (the source commit targets the 7.x root component):

* `.outer-wrapper` on 9-base already carries `[ngClass]="browserOsClasses…"`, a
  vanilla-9 feature 7.x does not have. Angular allows one `[ngClass]` per
  element, and overwriting it would silently drop `browser-firefox` /
  `browser-firefox-windows`, which `_custom_variables.scss` uses. The two are
  therefore merged into a single `outerWrapperClasses$` stream instead of
  pasting the source's `[ngClass]="'ds-admin-sidebar-' + (…)"`. A unit test
  guards the merge.
* the sidebar element is `<ds-admin-sidebar>` on v9, not
  `<ds-themed-admin-sidebar>`; that context line is left as it is.
* the source's trailing-comma reformat of the `windowService` constructor
  parameter is already present on 9-base, and `AfterViewInit` joins a
  multi-line `@angular/core` import, so those two hunks are no-ops here.

`slideSidebarPadding` itself is deliberately left in
`src/app/shared/animations/slide.ts`: after this change it still has one
consumer, the `custom` theme's `file-section.component.ts`.

Two unit tests are added beyond the source commit, which ships none. The v9
`root.component.spec.ts` had a single `it('should create')` that cannot detect
this regression. Both new tests were proven load-bearing with negative controls
(see the PR description).

Source: 1321b8a (dtq-dev PR #1350)

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: milanmajchrak

src/app/root/root.component.html

@@ -2,10 +2,9 @@
   {{ 'root.skip-to-content' | translate }}
 </button>
 
-<div class="outer-wrapper" [class.d-none]="shouldShowFullscreenLoader" [ngClass]="browserOsClasses.asObservable() | async" [@slideSidebarPadding]="{
-     value: ((isSidebarVisible$ | async) !== true ? 'hidden' : (slideSidebarOver$ | async) ? 'unpinned' : 'pinned'),
-     params: { collapsedWidth: (collapsedSidebarWidth$ | async), expandedWidth: (expandedSidebarWidth$ | async) }
-    }">
+<div class="outer-wrapper" [class.d-none]="shouldShowFullscreenLoader"
+     [class.ds-admin-sidebar-animate]="gutterTransitionEnabled"
+     [ngClass]="outerWrapperClasses$ | async">
   <ds-admin-sidebar [expandedSidebarWidth$]="expandedSidebarWidth$" [collapsedSidebarWidth$]="collapsedSidebarWidth$"></ds-admin-sidebar>
   <div class="inner-wrapper">
     <ds-system-wide-alert-banner></ds-system-wide-alert-banner>

src/app/root/root.component.scss

@@ -14,3 +14,31 @@
     top: 0;
   }
 }
+
+// Admin-sidebar left gutter. Driven by the `ds-admin-sidebar-*` class set in root.component.html (from
+// sidebarPaddingState$) rather than the @slideSidebarPadding Angular animation. The animation needed a
+// concrete width from the browser-only CSS-variable store, so on the server it rendered padding-left:0
+// and the authenticated page jumped right when the anti-flicker SSR snapshot was removed. Resolving the
+// gutter from the `--ds-admin-sidebar-*` custom properties in CSS instead renders identically on the
+// server (snapshot) and the browser (live app) - no hardcoded px, theme- and viewport-aware - and the
+// transition keeps the pin/unpin slide. 'hidden' (no admin sidebar) keeps the default padding-left: 0.
+.outer-wrapper {
+  // padding-left:0 (no admin sidebar); explicit for self-documentation.
+  &.ds-admin-sidebar-hidden {
+    padding-left: 0;
+  }
+
+  &.ds-admin-sidebar-unpinned {
+    padding-left: var(--ds-admin-sidebar-fixed-element-width);
+  }
+
+  &.ds-admin-sidebar-pinned {
+    padding-left: var(--ds-admin-sidebar-total-width);
+  }
+
+  // Slide only genuine pin/unpin toggles. The class is added after first paint (gutterTransitionEnabled)
+  // so the initial SSR->CSR gutter resolution behind the anti-flicker overlay never animates.
+  &.ds-admin-sidebar-animate {
+    transition: padding-left 300ms ease-in-out;
+  }
+}

src/app/root/root.component.spec.ts

@@ -7,6 +7,7 @@ import {
 import { NoopAnimationsModule } from '@angular/platform-browser/animations';
 import { Router } from '@angular/router';
 import { TranslateModule } from '@ngx-translate/core';
+import { of } from 'rxjs';
 
 import { AccessibilitySettingsService } from '../accessibility/accessibility-settings.service';
 import { AccessibilitySettingsServiceStub } from '../accessibility/accessibility-settings.service.stub';
@@ -72,4 +73,50 @@ describe('RootComponent', () => {
   it('should create', () => {
     expect(component).toBeTruthy();
   });
+
+  it('should emit the hidden gutter state when the admin sidebar is not visible', () => {
+    spyOn(TestBed.inject(MenuService), 'isMenuVisibleWithVisibleSections').and.returnValue(of(false));
+    component.ngOnInit();
+    component.browserOsClasses.next(['browser-firefox', 'browser-firefox-windows']);
+    fixture.detectChanges();
+
+    let state: string;
+    component.sidebarPaddingState$.subscribe((value: string) => state = value);
+    expect(state).toEqual('hidden');
+
+    // the gutter class must be merged with the browser/OS classes, not replace them
+    let classes: string[];
+    component.outerWrapperClasses$.subscribe((value: string[]) => classes = value);
+    expect(classes).toEqual(['browser-firefox', 'browser-firefox-windows', 'ds-admin-sidebar-hidden']);
+
+    const wrapper: HTMLElement = fixture.nativeElement.querySelector('.outer-wrapper');
+    expect(Array.from(wrapper.classList)).toContain('browser-firefox');
+    expect(Array.from(wrapper.classList)).toContain('browser-firefox-windows');
+    expect(Array.from(wrapper.classList)).toContain('ds-admin-sidebar-hidden');
+  });
+
+  it('should enable the gutter transition only after the first paint', () => {
+    const paints: FrameRequestCallback[] = [];
+    spyOn(window, 'requestAnimationFrame').and.callFake((callback: FrameRequestCallback) => {
+      paints.push(callback);
+      return 0;
+    });
+
+    const gutterFixture = TestBed.createComponent(RootComponent);
+    gutterFixture.detectChanges();
+    const wrapper: HTMLElement = gutterFixture.nativeElement.querySelector('.outer-wrapper');
+
+    // the gutter itself is rendered right away (this is what removes the SSR -> CSR jump) ...
+    expect(Array.from(wrapper.classList)).toContain('ds-admin-sidebar-pinned');
+    // ... but it must not animate before the first paint
+    expect(gutterFixture.componentInstance.gutterTransitionEnabled).toBeFalse();
+    expect(Array.from(wrapper.classList)).not.toContain('ds-admin-sidebar-animate');
+
+    expect(paints.length).toBeGreaterThan(0);
+    paints.forEach((callback: FrameRequestCallback) => callback(0));
+    gutterFixture.detectChanges();
+
+    expect(gutterFixture.componentInstance.gutterTransitionEnabled).toBeTrue();
+    expect(Array.from(wrapper.classList)).toContain('ds-admin-sidebar-animate');
+  });
 });

src/app/root/root.component.ts

@@ -3,6 +3,7 @@ import {
   NgClass,
 } from '@angular/common';
 import {
+  AfterViewInit,
   Component,
   Inject,
   Input,
@@ -38,7 +39,6 @@ import {
 } from '../core/services/window.service';
 import { ThemedFooterComponent } from '../footer/themed-footer.component';
 import { ThemedHeaderNavbarWrapperComponent } from '../header-nav-wrapper/themed-header-navbar-wrapper.component';
-import { slideSidebarPadding } from '../shared/animations/slide';
 import { HostWindowService } from '../shared/host-window.service';
 import { LiveRegionComponent } from '../shared/live-region/live-region.component';
 import { ThemedLoadingComponent } from '../shared/loading/themed-loading.component';
@@ -52,7 +52,6 @@ import { SystemWideAlertBannerComponent } from '../system-wide-alert/alert-banne
   selector: 'ds-base-root',
   templateUrl: './root.component.html',
   styleUrls: ['./root.component.scss'],
-  animations: [slideSidebarPadding],
   imports: [
     AsyncPipe,
     LiveRegionComponent,
@@ -68,12 +67,37 @@ import { SystemWideAlertBannerComponent } from '../system-wide-alert/alert-banne
     TranslateModule,
   ],
 })
-export class RootComponent implements OnInit {
+export class RootComponent implements OnInit, AfterViewInit {
   theme: Observable<ThemeConfig> = of({} as any);
   isSidebarVisible$: Observable<boolean>;
   slideSidebarOver$: Observable<boolean>;
   collapsedSidebarWidth$: Observable<string>;
   expandedSidebarWidth$: Observable<string>;
+
+  /**
+   * The admin-sidebar padding state ('hidden' | 'unpinned' | 'pinned') used to drive the
+   * outer-wrapper's left gutter via CSS classes (see root.component.scss) instead of an Angular
+   * animation. CSS resolves the gutter width from the `--ds-admin-sidebar-*` custom properties, so it
+   * is rendered identically on the server (the anti-flicker SSR snapshot) and the browser (the live
+   * app) - no browser-only CSS-variable read, no hardcoded px, and it stays theme- and viewport-aware.
+   */
+  sidebarPaddingState$: Observable<string>;
+
+  /**
+   * The classes on the outer wrapper: the browser/OS classes this branch already carries, plus the
+   * admin-sidebar gutter class. Merged into a single stream because Angular allows one [ngClass]
+   * binding per element and the wrapper already has one.
+   */
+  outerWrapperClasses$: Observable<string[]>;
+
+  /**
+   * Enables the gutter's `transition: padding-left` only AFTER the first browser paint. The initial
+   * SSR->CSR gutter resolution happens behind the anti-flicker overlay; without this gate a plain CSS
+   * transition would animate that initial 0->gutter change (the overlay settle detector only watches
+   * DOM mutations, not style changes), which could leak a 300ms slide right as the overlay is removed.
+   * Off on the server and on first render, so only genuine pin/unpin toggles animate.
+   */
+  gutterTransitionEnabled = false;
   notificationOptions: INotificationBoardOptions;
   models: any;
 
@@ -113,6 +137,8 @@ export class RootComponent implements OnInit {
 
     this.isSidebarVisible$ = this.menuService.isMenuVisibleWithVisibleSections(MenuID.ADMIN);
 
+    // Still provided to <ds-admin-sidebar>; the sidebar element itself sizes from CSS vars, so a
+    // null value on the server (the store is browser-only) is harmless there.
     this.expandedSidebarWidth$ = this.cssService.getVariable('--ds-admin-sidebar-total-width').pipe(
       skipWhile((val) => !val),
       first(),
@@ -129,11 +155,36 @@ export class RootComponent implements OnInit {
         startWith(true),
       );
 
+    // Drive the outer-wrapper gutter via a CSS class instead of the @slideSidebarPadding animation: the
+    // animation needs a concrete width from the browser-only CSS-variable store, so on the server it
+    // rendered padding-left:0 and the authenticated page jumped right when the SSR snapshot was removed.
+    // The CSS class resolves the gutter from `--ds-admin-sidebar-*` (see root.component.scss), identically
+    // on server and browser - fixing the jump without any hardcoded width.
+    this.sidebarPaddingState$ = combineLatestObservable([this.isSidebarVisible$, this.slideSidebarOver$]).pipe(
+      map(([visible, over]) => !visible ? 'hidden' : over ? 'unpinned' : 'pinned'),
+    );
+    this.outerWrapperClasses$ = combineLatestObservable([
+      this.browserOsClasses.asObservable(),
+      this.sidebarPaddingState$,
+    ]).pipe(
+      map(([osClasses, state]) => [...osClasses, `ds-admin-sidebar-${state}`]),
+    );
+
     if (this.router.url === getPageInternalServerErrorRoute()) {
       this.shouldShowRouteLoader = false;
     }
   }
 
+  ngAfterViewInit(): void {
+    // Enable the gutter slide only after the first paint (browser only; requestAnimationFrame is not
+    // defined under SSR), so the initial padding resolution never animates - see gutterTransitionEnabled.
+    if (typeof requestAnimationFrame === 'function') {
+      requestAnimationFrame(() => {
+        this.gutterTransitionEnabled = true;
+      });
+    }
+  }
+
   skipToMainContent() {
     const mainContent = document.getElementById('main-content');
     if (mainContent) {

src/themes/custom/app/root/root.component.ts

@@ -11,7 +11,6 @@ import { ThemedBreadcrumbsComponent } from '../../../../app/breadcrumbs/themed-b
 import { ThemedFooterComponent } from '../../../../app/footer/themed-footer.component';
 import { ThemedHeaderNavbarWrapperComponent } from '../../../../app/header-nav-wrapper/themed-header-navbar-wrapper.component';
 import { RootComponent as BaseComponent } from '../../../../app/root/root.component';
-import { slideSidebarPadding } from '../../../../app/shared/animations/slide';
 import { LiveRegionComponent } from '../../../../app/shared/live-region/live-region.component';
 import { ThemedLoadingComponent } from '../../../../app/shared/loading/themed-loading.component';
 import { NotificationsBoardComponent } from '../../../../app/shared/notifications/notifications-board/notifications-board.component';
@@ -23,7 +22,6 @@ import { SystemWideAlertBannerComponent } from '../../../../app/system-wide-aler
   styleUrls: ['../../../../app/root/root.component.scss'],
   // templateUrl: './root.component.html',
   templateUrl: '../../../../app/root/root.component.html',
-  animations: [slideSidebarPadding],
   imports: [
     AsyncPipe,
     LiveRegionComponent,