AI Implementation feature(880): Authenticated Shell, Quick Tabs and Change Password 1.04 (#19)
This commit was merged in pull request #19.
This commit is contained in:
@@ -1,178 +0,0 @@
|
||||
# Implementation Plan: Authenticated Shell — Component-Scoped LED Fix (Job 879, iteration 1.03)
|
||||
|
||||
## Status
|
||||
|
||||
The Job 879 reproduction shows that the LED `<span class="led led-running">`
|
||||
renders with zero size and transparent background even though the global
|
||||
`frontend/src/styles.css` declares the rules and the production bundle
|
||||
contains them. To guarantee the rules apply regardless of cascade order,
|
||||
external stylesheet loading, or specificity conflicts, this fix moves the
|
||||
LED's visual styling from the global stylesheet into the
|
||||
`ShellHeaderComponent` itself using Angular's
|
||||
`styles: [...]` (component-scoped CSS).
|
||||
|
||||
The component is a standalone component (no `styleUrls`), so the fix is a
|
||||
single, self-contained edit: add `styles: [\`...\`] to the `@Component`
|
||||
decorator in
|
||||
`frontend/src/app/features/shell/header/shell-header.component.ts`.
|
||||
The existing template, state class bindings, and `aria-label` are kept
|
||||
exactly as-is (lines 26–34).
|
||||
|
||||
A minimal regression test is added in a dedicated
|
||||
`tests/frontend/shell-led.spec.ts` that asserts the rendered `<span>`
|
||||
carries `led` plus the correct `led-<state>` class for each
|
||||
`EventState`, and that the bundled component CSS contains the four state
|
||||
selectors.
|
||||
|
||||
## 1. Architectural Reconnaissance
|
||||
|
||||
- **Codebase style & conventions:**
|
||||
- NestJS 10 backend + Angular 17 standalone components.
|
||||
- Standalone components use `imports: [...]` and prefer `styles: [\`...\`]`
|
||||
for small, co-located CSS. Existing examples in this repo:
|
||||
`frontend/src/app/features/setup/setup-create-admin.component.ts`
|
||||
uses `styleUrls: ['./setup-create-admin.component.css']`;
|
||||
`frontend/src/app/features/landing/landing.component.ts` likewise.
|
||||
For a small block of CSS that belongs to a single component, the
|
||||
inline `styles: [\`...\`] form keeps the fix in one file (per the
|
||||
user instruction: "Update the LED styling in
|
||||
frontend/src/app/features/shell/header/shell-header.component.ts near
|
||||
lines 25-34").
|
||||
- Angular's default `ViewEncapsulation.Emulated` rewrites component CSS
|
||||
selectors with attribute selectors (`[_ngcontent-xxx]`) and adds the
|
||||
same attribute to the component's host + template nodes. Because the
|
||||
LED `<span>` is rendered by `ShellHeaderComponent` (not by a child
|
||||
component or via `innerHTML`), encapsulation correctly scopes the new
|
||||
rules to that span, while still allowing the global `:root` CSS
|
||||
custom-property tokens (`--color-success`, etc.) to be inherited.
|
||||
|
||||
- **Data Layer:** Not impacted. The LED color is driven by
|
||||
`eventState()` from `EventStatusStore` (already wired).
|
||||
|
||||
- **Test Framework & Structure:**
|
||||
- Jest 29 multi-project config (`tests/jest.config.js`).
|
||||
- Frontend project uses `ts-jest` + jsdom +
|
||||
`tests/frontend/jest.setup.ts` (Angular TestBed shims).
|
||||
- Tests MUST live in `tests/frontend/` — never alongside source. They
|
||||
MUST run via `npm test` (single root command). Tests MUST NOT
|
||||
require a UI; this plan keeps them purely structural.
|
||||
|
||||
- **Required Tools & Dependencies:** None new. Existing
|
||||
`@angular-devkit/build-angular:application` builder already supports
|
||||
component-scoped `styles: [\`...\`] `, and `critters` (used for inline
|
||||
above-the-fold CSS) is unaffected. `setup.sh` needs no changes.
|
||||
|
||||
## 2. Impacted Files
|
||||
|
||||
- **To Modify:**
|
||||
- `frontend/src/app/features/shell/header/shell-header.component.ts`
|
||||
— add a `styles: [\`...\`] block to the `@Component` decorator that
|
||||
mirrors the LED rules from the global stylesheet, scoped to the
|
||||
component. Keep the existing template (lines 10–88) untouched.
|
||||
Keep the `[class.led-<state>]` bindings and the dynamic `aria-label`.
|
||||
|
||||
- **To Create:**
|
||||
- `tests/frontend/shell-led.spec.ts` — minimal jsdom-based test that
|
||||
renders `ShellHeaderComponent` with each `EventState` value and
|
||||
asserts (a) the rendered `[data-testid="shell-led"]` carries the
|
||||
`led` class plus the matching `led-<state>` class, and (b) the
|
||||
component's bundled CSS string contains the four required state
|
||||
selectors (`led-running`, `led-countdown`, `led-stopped`,
|
||||
`led-unconfigured`).
|
||||
|
||||
## 3. Proposed Changes
|
||||
|
||||
1. **Component-scoped CSS in `ShellHeaderComponent`**
|
||||
In
|
||||
`frontend/src/app/features/shell/header/shell-header.component.ts`,
|
||||
add a `styles` property to the `@Component` decorator. Place it
|
||||
immediately after the existing `imports: [CommonModule]` property
|
||||
(around the current line 9 area) so the decorator remains in
|
||||
canonical Angular order: `selector`, `standalone`, `changeDetection`,
|
||||
`imports`, `template`, `styles`.
|
||||
|
||||
Exact CSS block to add inside the backtick literal:
|
||||
|
||||
```
|
||||
:host .led,
|
||||
.led {
|
||||
display: inline-block;
|
||||
width: 10px;
|
||||
height: 10px;
|
||||
border-radius: 50%;
|
||||
border: 0;
|
||||
background-color: transparent;
|
||||
vertical-align: middle;
|
||||
}
|
||||
.led-running { background-color: var(--color-success); }
|
||||
.led-countdown { background-color: var(--color-warning); }
|
||||
.led-stopped { background-color: var(--color-danger); }
|
||||
.led-unconfigured { background-color: var(--color-secondary); }
|
||||
```
|
||||
|
||||
Notes:
|
||||
- The base rule is duplicated as `:host .led, .led` so it matches
|
||||
both a projected host usage and the in-template span. The
|
||||
`:host` selector is harmless under Emulated encapsulation (it
|
||||
targets the component's own host element) and does not break the
|
||||
existing template.
|
||||
- State classes are written exactly as before — the template already
|
||||
toggles `[class.led-running]`, `[class.led-countdown]`,
|
||||
`[class.led-stopped]`, `[class.led-unconfigured]`.
|
||||
- Color values use the existing `:root` CSS custom properties
|
||||
(`--color-success`/`--color-warning`/`--color-danger`/
|
||||
`--color-secondary`) defined in `frontend/src/styles.css`. These
|
||||
tokens are inherited through the DOM, so the component-scoped
|
||||
rules resolve them automatically — no per-state hex is needed in
|
||||
TypeScript.
|
||||
- The current global rules in `frontend/src/styles.css` (lines 23–27)
|
||||
are left untouched as a safety net; they remain correct and
|
||||
harmless.
|
||||
|
||||
2. **No template or state-binding changes**
|
||||
The `<span ... class="led" [class.led-running]="..." ...>`
|
||||
block (lines 26–34) and the dynamic `aria-label` are kept exactly
|
||||
as the documentation in
|
||||
`docs/guides/authenticated-shell.md` specifies.
|
||||
|
||||
3. **No backend / DB changes**
|
||||
The bug is purely a frontend cascade issue.
|
||||
|
||||
## 4. Test Strategy
|
||||
|
||||
- **Target Unit Test File:** `tests/frontend/shell-led.spec.ts`
|
||||
(new file, in the dedicated `tests/frontend/` folder per repo
|
||||
convention; runs via `npm test` -> `jest --config tests/jest.config.js
|
||||
--selectProjects frontend`).
|
||||
|
||||
- **Mocking Strategy:**
|
||||
- Use Angular's `TestBed.configureTestingModule({ imports:
|
||||
[ShellHeaderComponent] })` so the component renders standalone
|
||||
in jsdom with no router / http mocking required (the LED span has
|
||||
no dependencies).
|
||||
- Provide minimal inputs via the component's `input.required<...>` /
|
||||
`input<...>(...)` signals. Specifically, set `eventState()` to
|
||||
each of `'running' | 'countdown' | 'stopped' | 'unconfigured'`
|
||||
using `TestBed.runInInjectionContext` + `ComponentRef.setInput`
|
||||
(or `fixture.componentRef.setInput`) and assert the DOM.
|
||||
- No HTTP, no router, no SSE — keeping the test fast and isolated.
|
||||
- Two compact assertions per case:
|
||||
1. `expect(led.classList.contains('led')).toBe(true)` and the
|
||||
matching `led-<state>` class.
|
||||
2. Read the component's raw `styles` string (via the decorated
|
||||
component's static `ɵcmp.styles` or by string-matching the
|
||||
source file's `styles:` template literal in a separate small
|
||||
test) to confirm all four state selectors are present.
|
||||
Concretely: a single test that imports the component file as
|
||||
text (via `fs.readFileSync` of the TS source — same pattern
|
||||
other frontend tests already use for inspecting contracts) and
|
||||
asserts it contains
|
||||
`.led-running`, `.led-countdown`, `.led-stopped`,
|
||||
`.led-unconfigured`, plus `width: 10px`, `height: 10px`,
|
||||
`border-radius: 50%`, and `var(--color-success)`.
|
||||
|
||||
- **What is NOT tested (per instructions):** no visual / screenshot
|
||||
confirmation, no jsdom layout reflow assertions, no large mock SSE
|
||||
harness — only the structural class binding and the presence of
|
||||
the component-scoped CSS rules. This matches the
|
||||
"minimal, highly-focused tests" instruction.
|
||||
@@ -0,0 +1,30 @@
|
||||
# Implementation Plan: Authenticated Shell LED Visibility Fix
|
||||
|
||||
## 1. Architectural Reconnaissance
|
||||
- **Codebase style & conventions:** Node.js monorepo with an Angular 17 standalone-component SPA and NestJS backend. The authenticated shell uses OnPush components, signal inputs/outputs, inline Angular templates/styles, and theme CSS custom properties. `HomeComponent` owns event-stream lifecycle and passes `EventStatusStore.state()` into the presentational `ShellHeaderComponent`. Quick tabs and change-password behavior are already implemented and are not implicated in this regression.
|
||||
- **Data Layer:** TypeORM-backed backend settings provide `eventStartUtc` and `eventEndUtc`; no schema or persistence changes are required. The backend event-state calculation and authenticated SSE payload are already functioning: the shell receives the correct `running`, `countdown`, `stopped`, or `unconfigured` state and applies the matching class.
|
||||
- **Test Framework & Structure:** Root Jest 29 multi-project configuration with `ts-jest`; frontend tests run in jsdom from the dedicated `tests/frontend/` directory. `npm test` runs all backend and frontend tests, while `npm run test:frontend` runs the frontend project only. Existing `tests/frontend/shell-led.spec.ts` is a source-structure assertion and does not instantiate the component or verify the rendered style binding.
|
||||
- **Required Tools & Dependencies:** No new system tools, global CLIs, npm packages, persistent `/data` assets, or `setup.sh` changes are required. Existing Angular, Jest, jsdom, and TypeScript dependencies are sufficient.
|
||||
|
||||
## 2. Impacted Files
|
||||
- **To Modify:**
|
||||
- `frontend/src/app/features/shell/header/shell-header.component.ts` — remove the conflicting transparent base declaration and bind the state-specific background color directly on the LED element so the browser paints the themed color reliably.
|
||||
- `tests/frontend/shell-led.spec.ts` — replace/extend brittle source-only assertions with a focused automated regression covering the style value produced for each event state and preserving the accessible state label.
|
||||
- **To Create:** None.
|
||||
|
||||
## 3. Proposed Changes
|
||||
1. **Database / Schema Migration:** None. Event timestamps, settings storage, REST/SSE contracts, and backend state computation remain unchanged.
|
||||
2. **Backend Logic & APIs:** None. `/api/v1/events/status` already emits the correct state, and `EventStatusStore` already forwards it to the shell.
|
||||
3. **Frontend UI Integration:**
|
||||
1. In `ShellHeaderComponent`, define a typed state-to-theme-color mapping for all `EventState` values: `running` → `var(--color-success)`, `countdown` → `var(--color-warning)`, `stopped` → `var(--color-danger)`, and `unconfigured` → `var(--color-secondary)`.
|
||||
2. Replace the unused `ledClass` computed value with a computed background-color value derived from `eventState()`; keep the existing state class bindings because they are useful selectors and preserve the current DOM contract.
|
||||
3. Bind the computed value directly to the LED span's `style.background-color`. This gives the element an explicit non-transparent author value while continuing to resolve the active theme token at runtime, matching the reported proof that a direct targeted declaration makes the dot visible.
|
||||
4. Remove `background-color: transparent` from the component base `.led` rule, and remove the redundant component state-color declarations if the inline binding becomes the single authoritative color source. Retain only the shape/layout styling (`inline-block`, 10×10 dimensions, circular radius, border, alignment).
|
||||
5. Remove the global LED state rules from `frontend/src/styles.css` if they are no longer consumed, avoiding duplicate ownership and future cascade ambiguity; keep canonical theme token declarations untouched.
|
||||
6. Preserve the existing `data-testid`, four state classes, and `aria-label="Event status: <state>"`, so status remains exposed textually rather than by color alone.
|
||||
7. Do not modify `HomeComponent`, `QuickTabsComponent`, change-password components, event store, routes, SSE transport, or backend services because repository tracing shows those layers already deliver the correct state and shell behavior.
|
||||
|
||||
## 4. Test Strategy
|
||||
- **Target Unit Test File:** `tests/frontend/shell-led.spec.ts`.
|
||||
- **Mocking Strategy:** No backend, HTTP, SSE, timers, filesystem fixtures, browser automation, or persistent data. Exercise a small exported pure state-to-color helper (or equivalent component mapping) with table-driven assertions for the four states, and retain focused source/template assertions that the LED consumes that value through `[style.background-color]`, keeps each state class binding, and keeps the dynamic `aria-label`. This directly prevents a regression to a transparent base color while remaining fast and CLI-only under `npm test`.
|
||||
- **Verification Commands for the implementer:** Run `npm run test:frontend`, `npm test`, and `npm run build` from `/repo`. The root build compiles both Angular and NestJS; no separate lint or typecheck script is defined.
|
||||
Reference in New Issue
Block a user