docs: add implementation plan for the environment indicator banner
This commit is contained in:
Bastian Wagner
355
docs/superpowers/plans/2026-08-05-env-indicator.md
Normal file
355
docs/superpowers/plans/2026-08-05-env-indicator.md
Normal file
@@ -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 `<router-outlet />` 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) {
|
||||
<div class="env-banner" role="status">⚠ Entwicklungsumgebung</div>
|
||||
}
|
||||
```
|
||||
|
||||
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: `<app-root>` 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
|
||||
<app-env-banner />
|
||||
<router-outlet />
|
||||
```
|
||||
|
||||
- [ ] **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 `<app-root>`-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.
|
||||
Reference in New Issue
Block a user