diff --git a/docs/superpowers/plans/2026-08-05-env-indicator.md b/docs/superpowers/plans/2026-08-05-env-indicator.md new file mode 100644 index 0000000..99cff56 --- /dev/null +++ b/docs/superpowers/plans/2026-08-05-env-indicator.md @@ -0,0 +1,355 @@ +# Umgebungs-Indikator (EnvBanner) Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Ein schmaler Banner-Streifen erscheint app-weit oben, sobald `environment.production === false` (aktuell nur der lokale `ng serve`-Build), damit man Entwicklungsumgebung und echte App nie verwechselt. + +**Architecture:** Neue Standalone-Komponente `EnvBanner` wird einmalig in `app.html` vor `` eingebunden (single source of truth für alle Routen). `App` (Root-Komponente) bindet zusätzlich eine CSS-Custom-Property `--env-banner-height` auf ihr eigenes Host-Element, damit die drei `height:100dvh`-Layouts (Shell, Public-Team, Public-Player) die Banner-Höhe kompensieren können, ohne den kürzlich behobenen Doppel-Scrollbar-Bug erneut einzuführen. + +**Tech Stack:** Angular 21 (Standalone Components, Signals, neue Control-Flow-Syntax), SCSS, Vitest. + +## Global Constraints + +- Banner-Höhe ist eine feste Konstante `ENV_BANNER_HEIGHT_PX = 28` (Pixel), exportiert aus `env-banner.ts` und in `app.ts` wiederverwendet — an genau diesen zwei Stellen referenziert, nicht dupliziert. +- Banner-Text ist exakt `⚠ Entwicklungsumgebung` — keine zusätzlichen technischen Details (API-URL, Build-Hash). +- Banner-Farbe ist Amber/Orange (`#f4a300` Hintergrund, `#20251F` Text) — bewusst nicht das App-Grün (`--mat-sys-primary`). +- Kein Dismiss/Schließen-Button. +- Kein neues Feld in den drei Environment-Dateien — einzige Quelle ist das bereits vorhandene `environment.production` (siehe `docs/superpowers/specs/2026-08-05-env-indicator-design.md`, Abschnitt „Entscheidungen aus dem Brainstorming"). +- `EnvBanner` wird ausschließlich einmal in `app.html` eingebunden, nicht zusätzlich in Shell/Public-Seiten/Auth-Seiten. + +--- + +### Task 1: `EnvBanner`-Komponente + +**Files:** +- Create: `myteamwallet_frontend_modern/src/app/shared/env-banner/env-banner.ts` +- Create: `myteamwallet_frontend_modern/src/app/shared/env-banner/env-banner.html` +- Create: `myteamwallet_frontend_modern/src/app/shared/env-banner/env-banner.scss` +- Test: `myteamwallet_frontend_modern/src/app/shared/env-banner/env-banner.spec.ts` + +**Interfaces:** +- Consumes: `environment` aus `myteamwallet_frontend_modern/src/environments/environment.ts` (Feld `production: boolean`, per Angular `fileReplacements` je Build-Konfiguration ausgetauscht — bereits vorhanden, keine Änderung nötig). +- Produces: `export class EnvBanner` (Selector `app-env-banner`, keine Inputs) und `export const ENV_BANNER_HEIGHT_PX = 28;` — beide werden in Task 2 von `app.ts` importiert. + +- [ ] **Step 1: Fehlschlagenden Test schreiben** + +Erstelle `myteamwallet_frontend_modern/src/app/shared/env-banner/env-banner.spec.ts`: + +```ts +import { TestBed } from '@angular/core/testing'; +import { EnvBanner } from './env-banner'; +import { environment } from '../../../environments/environment'; + +describe('EnvBanner', () => { + const originalProduction = environment.production; + + afterEach(() => { + environment.production = originalProduction; + }); + + it('shows the environment banner outside production', async () => { + environment.production = false; + await TestBed.configureTestingModule({ imports: [EnvBanner] }).compileComponents(); + const fixture = TestBed.createComponent(EnvBanner); + fixture.detectChanges(); + + const element = fixture.nativeElement.querySelector('.env-banner'); + expect(element?.textContent).toContain('Entwicklungsumgebung'); + }); + + it('renders nothing in production', async () => { + environment.production = true; + await TestBed.configureTestingModule({ imports: [EnvBanner] }).compileComponents(); + const fixture = TestBed.createComponent(EnvBanner); + fixture.detectChanges(); + + const element = fixture.nativeElement.querySelector('.env-banner'); + expect(element).toBeNull(); + }); +}); +``` + +- [ ] **Step 2: Test ausführen und Fehlschlag bestätigen** + +Run: `cd myteamwallet_frontend_modern && npx ng test --watch=false --include='**/env-banner.spec.ts'` +Expected: FAIL — `Cannot find module './env-banner'` (die Komponente existiert noch nicht). + +- [ ] **Step 3: Komponente implementieren** + +Erstelle `myteamwallet_frontend_modern/src/app/shared/env-banner/env-banner.ts`: + +```ts +import { Component } from '@angular/core'; +import { environment } from '../../../environments/environment'; + +export const ENV_BANNER_HEIGHT_PX = 28; + +@Component({ + selector: 'app-env-banner', + templateUrl: './env-banner.html', + styleUrl: './env-banner.scss', +}) +export class EnvBanner { + protected readonly showBanner = !environment.production; +} +``` + +Erstelle `myteamwallet_frontend_modern/src/app/shared/env-banner/env-banner.html`: + +```html +@if (showBanner) { +
⚠ Entwicklungsumgebung
+} +``` + +Erstelle `myteamwallet_frontend_modern/src/app/shared/env-banner/env-banner.scss`: + +```scss +// Höhe muss mit ENV_BANNER_HEIGHT_PX in env-banner.ts übereinstimmen. +.env-banner { + height: 28px; + flex-shrink: 0; + display: flex; + align-items: center; + justify-content: center; + background: #f4a300; + color: #20251f; + font-weight: 700; + font-size: 0.75rem; + letter-spacing: 0.04em; + text-transform: uppercase; +} +``` + +- [ ] **Step 4: Test ausführen und Erfolg bestätigen** + +Run: `cd myteamwallet_frontend_modern && npx ng test --watch=false --include='**/env-banner.spec.ts'` +Expected: PASS — beide Tests grün. + +- [ ] **Step 5: Commit** + +```bash +cd myteamwallet_frontend_modern +git add src/app/shared/env-banner/ +git commit -m "feat: add EnvBanner component for non-production environments + +Standalone component that renders a small banner whenever +environment.production is false, so the local dev build is never +mistaken for the real app." +``` + +--- + +### Task 2: Einbau in `App` (Root-Komponente) inkl. Höhen-Variable + +**Files:** +- Modify: `myteamwallet_frontend_modern/src/app/app.ts` +- Modify: `myteamwallet_frontend_modern/src/app/app.html` +- Create: `myteamwallet_frontend_modern/src/app/app.spec.ts` (existiert noch nicht) + +**Interfaces:** +- Consumes: `EnvBanner`, `ENV_BANNER_HEIGHT_PX` aus Task 1 (`myteamwallet_frontend_modern/src/app/shared/env-banner/env-banner.ts`); `environment` aus `myteamwallet_frontend_modern/src/environments/environment.ts`. +- Produces: `` setzt die Inline-Style-Custom-Property `--env-banner-height` (Wert inkl. `px`-Einheit, z. B. `"28px"` oder `"0px"`) auf seinem eigenen Host-Element. Task 3 liest diese Property per `var(--env-banner-height, 0px)`. + +- [ ] **Step 1: Fehlschlagenden Test schreiben** + +Erstelle `myteamwallet_frontend_modern/src/app/app.spec.ts`: + +```ts +import { TestBed } from '@angular/core/testing'; +import { provideHttpClient } from '@angular/common/http'; +import { provideHttpClientTesting } from '@angular/common/http/testing'; +import { provideRouter } from '@angular/router'; +import { App } from './app'; +import { environment } from '../environments/environment'; + +describe('App', () => { + const originalProduction = environment.production; + + beforeEach(() => { + localStorage.clear(); + }); + + afterEach(() => { + environment.production = originalProduction; + }); + + it('sets --env-banner-height to 0px and renders no banner in production', async () => { + environment.production = true; + await TestBed.configureTestingModule({ + imports: [App], + providers: [provideHttpClient(), provideHttpClientTesting(), provideRouter([])], + }).compileComponents(); + const fixture = TestBed.createComponent(App); + fixture.detectChanges(); + + expect(fixture.nativeElement.style.getPropertyValue('--env-banner-height')).toBe('0px'); + expect(fixture.nativeElement.querySelector('.env-banner')).toBeNull(); + }); + + it('sets --env-banner-height to 28px and renders the banner outside production', async () => { + environment.production = false; + await TestBed.configureTestingModule({ + imports: [App], + providers: [provideHttpClient(), provideHttpClientTesting(), provideRouter([])], + }).compileComponents(); + const fixture = TestBed.createComponent(App); + fixture.detectChanges(); + + expect(fixture.nativeElement.style.getPropertyValue('--env-banner-height')).toBe('28px'); + expect(fixture.nativeElement.querySelector('.env-banner')).not.toBeNull(); + }); +}); +``` + +- [ ] **Step 2: Test ausführen und Fehlschlag bestätigen** + +Run: `cd myteamwallet_frontend_modern && npx ng test --watch=false --include='**/app.spec.ts'` +Expected: FAIL — `--env-banner-height` ist leer (`''`), kein `.env-banner`-Element vorhanden. + +- [ ] **Step 3: `App` erweitern** + +In `myteamwallet_frontend_modern/src/app/app.ts`, den bestehenden Inhalt ersetzen durch: + +```ts +import { Component, inject } from '@angular/core'; +import { RouterOutlet } from '@angular/router'; +import { AuthApi } from './core/auth/auth-api'; +import { AuthStore } from './core/auth/auth-store'; +import { environment } from '../environments/environment'; +import { ENV_BANNER_HEIGHT_PX, EnvBanner } from './shared/env-banner/env-banner'; + +@Component({ + selector: 'app-root', + imports: [RouterOutlet, EnvBanner], + templateUrl: './app.html', + styleUrl: './app.scss', + host: { + '[style.--env-banner-height]': 'bannerHeight', + }, +}) +export class App { + private readonly authApi = inject(AuthApi); + private readonly authStore = inject(AuthStore); + protected readonly bannerHeight = `${environment.production ? 0 : ENV_BANNER_HEIGHT_PX}px`; + + constructor() { + if (this.authStore.token()) { + this.authApi.me().subscribe({ + next: (response) => { + const { token, ...user } = response; + if (token) { + this.authStore.setSession(token, user); + } else { + this.authStore.updateUser(user); + } + }, + error: () => undefined, + }); + } + } +} +``` + +(Nur `imports`, `host` und die neue `bannerHeight`-Property sind neu — Konstruktor-Logik unverändert übernommen.) + +In `myteamwallet_frontend_modern/src/app/app.html`, den bestehenden Inhalt ersetzen durch: + +```html + + +``` + +- [ ] **Step 4: Test ausführen und Erfolg bestätigen** + +Run: `cd myteamwallet_frontend_modern && npx ng test --watch=false --include='**/app.spec.ts'` +Expected: PASS — beide Tests grün. + +- [ ] **Step 5: Commit** + +```bash +cd myteamwallet_frontend_modern +git add src/app/app.ts src/app/app.html src/app/app.spec.ts +git commit -m "feat: mount EnvBanner app-wide and expose --env-banner-height + +Renders the banner once at the app root so every route picks it up, +and exposes its height as a CSS custom property so fixed-viewport +layouts (Shell, public pages) can compensate for it." +``` + +--- + +### Task 3: Höhen-Kompensation in den `100dvh`-Layouts + +**Files:** +- Modify: `myteamwallet_frontend_modern/src/app/core/layout/shell/shell.scss` +- Modify: `myteamwallet_frontend_modern/src/app/features/public-team/public-team.scss` +- Modify: `myteamwallet_frontend_modern/src/app/features/public-team/public-player.scss` + +**Interfaces:** +- Consumes: `--env-banner-height` Custom Property aus Task 2, gelesen per `var(--env-banner-height, 0px)` — der Fallback `0px` ist notwendig, damit `shell.spec.ts`, `public-team.spec.ts` und `public-player.spec.ts` (die diese Komponenten isoliert ohne ``-Ancestor rendern) unverändert weiter grün bleiben. + +Diese drei Dateien nutzen aktuell `height: 100dvh;` als feste Zusage „genau ein Bildschirm hoch" (siehe `docs/superpowers/plans/die-public-seite-kann-async-shamir.md` vom selben Tag zum Doppel-Scrollbar-Fix). Ohne Anpassung würde der neue Banner die Shell/Public-Seite um seine Höhe über den sichtbaren Bereich hinausschieben — derselbe Bugtyp wie der dort behobene. + +- [ ] **Step 1: `shell.scss` anpassen** + +In `myteamwallet_frontend_modern/src/app/core/layout/shell/shell.scss`, im `:host`-Block: + +```scss +// vorher: height: 100dvh; +height: calc(100dvh - var(--env-banner-height, 0px)); +``` + +- [ ] **Step 2: `public-team.scss` anpassen** + +In `myteamwallet_frontend_modern/src/app/features/public-team/public-team.scss`, im `:host`-Block dieselbe Änderung: + +```scss +height: calc(100dvh - var(--env-banner-height, 0px)); +``` + +- [ ] **Step 3: `public-player.scss` anpassen** + +In `myteamwallet_frontend_modern/src/app/features/public-team/public-player.scss`, im `:host`-Block dieselbe Änderung: + +```scss +height: calc(100dvh - var(--env-banner-height, 0px)); +``` + +- [ ] **Step 4: Vollständige Test-Suite laufen lassen** + +Run: `cd myteamwallet_frontend_modern && npx ng test --watch=false` +Expected: alle Tests weiterhin PASS — reine CSS-Wertänderung, `shell.spec.ts`/`public-team.spec.ts`/`public-player.spec.ts` prüfen kein Layout und bleiben unberührt. + +- [ ] **Step 5: Build laufen lassen** + +Run: `cd myteamwallet_frontend_modern && npx ng build` +Expected: Build erfolgreich (nur die bereits bekannte, unveränderte Bundle-Budget-Warnung). + +- [ ] **Step 6: Manuelle Verifikation (kein automatisierter CSS-Layout-Test im Projekt vorhanden)** + +`npm start`, im Browser (z. B. via Chrome DevTools) auf einer Shell-Seite mit langer Liste (`/team/:id/overview`) sowie auf `/t/:token` mit Inhalt prüfen: +- Banner ist sichtbar, Header darunter bleibt beim Scrollen fix, Bottom-Nav ist vollständig sichtbar (nicht abgeschnitten). +- `document.body.scrollHeight === document.body.clientHeight` (kein zusätzlicher Scrollbar auf `body`, wie beim vorherigen Fix verifiziert). +- `ng build` (ohne `--configuration`, also production) und `ng build --configuration=container` zeigen keinen Banner (visuell/Bundle prüfen), `ng serve` (development) zeigt ihn. + +- [ ] **Step 7: Commit** + +```bash +cd myteamwallet_frontend_modern +git add src/app/core/layout/shell/shell.scss src/app/features/public-team/public-team.scss src/app/features/public-team/public-player.scss +git commit -m "fix: compensate 100dvh layouts for the env banner's height + +Shell and the public pages commit to exactly one viewport tall; without +this, the new dev-environment banner would push their bottom edge (and +Shell's bottom nav) past the visible viewport, the same overflow-leak +bug fixed earlier today." +``` + +--- + +## Self-Review Notes + +- **Spec-Abdeckung:** Komponente + Sichtbarkeitslogik (Task 1), App-weite Einbindung + Höhen-Variable (Task 2), Höhen-Kompensation der drei betroffenen Layouts (Task 3) — alle Abschnitte der Spec sind abgedeckt. Kein neues Environment-Feld (bewusst, siehe Spec). +- **Typkonsistenz:** `ENV_BANNER_HEIGHT_PX` einmal in `env-banner.ts` definiert, in `app.ts` importiert und verwendet — keine Duplikation des Zahlenwerts außer dem dokumentierten Kommentar in `env-banner.scss`. `bannerHeight` liefert einen fertigen `px`-String statt eine Zahl mit `[style.prop.px]`-Unit-Suffix, da Angulars Unit-Suffix-Syntax für CSS-Custom-Properties (`--foo`) nicht zuverlässig dokumentiert/getestet ist — sicherer, den fertigen String zu binden. +- **Scope:** Einzelne, in sich geschlossene Erweiterung; keine weitere Zerlegung nötig.