From 29b447d51f9728305c28439fac3ea3701d811594 Mon Sep 17 00:00:00 2001 From: m0rph3us1987 Date: Thu, 23 Jul 2026 10:37:53 +0000 Subject: [PATCH] AI Implementation feature(914): Admin Area Blog and Blog Page 1.00 (#59) --- .kilo/plans/870.md | 82 ------------------- .kilo/plans/914.md | 65 +++++++++++++++ docs/architecture/frontend-structure.md | 2 +- docs/guides/blog.md | 10 ++- docs/index.md | 2 +- .../admin/blog/blog-form-modal.component.ts | 6 ++ tests/frontend/blog-form-modal-escape.spec.ts | 67 +++++++++++++++ 7 files changed, 149 insertions(+), 85 deletions(-) delete mode 100644 .kilo/plans/870.md create mode 100644 .kilo/plans/914.md create mode 100644 tests/frontend/blog-form-modal-escape.spec.ts diff --git a/.kilo/plans/870.md b/.kilo/plans/870.md deleted file mode 100644 index c4ba9f3..0000000 --- a/.kilo/plans/870.md +++ /dev/null @@ -1,82 +0,0 @@ -# Fix Plan: TS2459 PostFormSubmitPayload not exported - -## 1. Root Cause - -`frontend/src/app/features/admin/blog/blog-form.pure.ts` declares `PostFormSubmitPayload` and `PostFormMode` as exports, but `frontend/src/app/features/admin/blog/blog-form-modal.component.ts` only **imports** them — it does not re-export them. - -`frontend/src/app/features/admin/blog/blog.component.ts:10` imports `PostFormSubmitPayload` from `./blog-form-modal.component`, which has no such export. Under `ng build --configuration production` (which uses `compilationMode: "full"` Angular strict template/type-check), this is a hard `TS2459` error and the bundle fails. - -The existing codebase convention is the opposite: `category-form-modal.component.ts` declares `CategoryFormSubmit` / `CategoryFormMode` **inside** the modal file and consumers (`categories.component.ts`) import them from the modal component directly. My initial layout diverged from that pattern by colocating the modal-output types in the `.pure.ts` module. - -## 2. Fix (chosen approach: match the existing `CategoryFormSubmit` convention) - -Move the two UI-emit types out of `blog-form.pure.ts` and into `blog-form-modal.component.ts`, then update the two importers. - -### 2.1 `frontend/src/app/features/admin/blog/blog-form-modal.component.ts` (modify) - -Add at the top (right after the existing imports from `./blog-form.pure`): - -```ts -export type PostFormMode = 'create' | 'edit'; - -export interface PostFormSubmitPayload { - mode: PostFormMode; - title: string; - bodyMd: string; - action: 'draft' | 'publish'; -} -``` - -Remove these two names from the import list at line 19-20: - -```ts -// before -import { - PostFormGroup, - PostFormMode, // ← remove - PostFormSubmitPayload, // ← remove - buildPostBody, - syncPostForm, - validatePostForm, -} from './blog-form.pure'; - -// after -import { - PostFormGroup, - buildPostBody, - syncPostForm, - validatePostForm, -} from './blog-form.pure'; -``` - -`PostFormGroup` stays imported from the `.pure.ts` module (it is the pure form-shape type, used internally by the modal). - -### 2.2 `frontend/src/app/features/admin/blog/blog-form.pure.ts` (modify) - -Remove the two declarations (lines 4 and 11-16) so the pure module no longer leaks UI-emit types: - -- Delete `export type PostFormMode = 'create' | 'edit';` -- Delete the entire `export interface PostFormSubmitPayload { ... }` block. - -Keep the rest of the file unchanged: -- `PostFormGroup` -- `MAX_TITLE_LENGTH` / `MAX_BODY_LENGTH` -- `validatePostForm`, `syncPostForm`, `buildPostBody`, `statusBadgeClass`, `statusLabel` - -### 2.3 No other edits required - -- `frontend/src/app/features/admin/blog/blog.component.ts` already imports `PostFormSubmitPayload` from `./blog-form-modal.component` — after step 2.1 that import resolves correctly. No change. -- `tests/frontend/blog-admin-form.spec.ts` does **not** import `PostFormMode` or `PostFormSubmitPayload` (verified — only `PostFormGroup`, `buildPostBody`, `statusBadgeClass`, `statusLabel`, `syncPostForm`, `validatePostForm`). No change. -- `tests/frontend/blog-page.spec.ts` is unaffected. - -## 3. Verification - -After the fix: - -1. `cd /repo && npx ng build --configuration production` must succeed (the original failing command). -2. `cd /repo && npm test` must continue to pass (89 suites, 678 tests). -3. The `BlogFormModalComponent.submit` output still emits the same `PostFormSubmitPayload` shape — `blog.component.ts:onFormSubmit` is unchanged. - -## 4. Why this fix over the alternative - -Alternative considered: change the import in `blog.component.ts` from `'./blog-form-modal.component'` to `'./blog-form.pure'`. This is a one-line change but it diverges from the established `CategoryFormSubmit` pattern (modal-emit types live with the modal), and it forces every future consumer of the form payload to import from the `.pure.ts` module instead of the modal. The chosen fix aligns this feature with the rest of the codebase and keeps the modal's public API self-contained. diff --git a/.kilo/plans/914.md b/.kilo/plans/914.md new file mode 100644 index 0000000..5346245 --- /dev/null +++ b/.kilo/plans/914.md @@ -0,0 +1,65 @@ +# Implementation Plan: Job 914 — Escape must close the New post overlay without saving + +## 1. Architectural Reconnaissance + +- **Codebase style & conventions:** + - Angular 17+ standalone components, `ChangeDetectionStrategy.OnPush`, signal inputs (`input()`), signal outputs (`output()`), the new `@if` control flow, and `effect()` for reactive side effects. + - Backend is NestJS with TypeORM; out of scope for this Job (no DB/API changes). + - The frontend admin blog feature lives under `frontend/src/app/features/admin/blog/`. The pure helpers live in `blog-form.pure.ts`; the modal is `blog-form-modal.component.ts`; the smart page is `blog.component.ts`. + - **Escape-to-close is the established convention for every modal in this codebase.** Every other modal uses `@HostListener('document:keydown.escape')` on the component class and emits its `cancel` output: + - `frontend/src/app/features/setup/setup-create-admin.component.ts:103` + - `frontend/src/app/features/admin/player-delete-modal.component.ts:61` + - `frontend/src/app/features/shell/change-password/change-password-modal.component.ts:156` + - `frontend/src/app/features/challenges/challenge-modal.component.ts:174` + - `frontend/src/app/features/admin/challenges/challenge-import-modal.component.ts:105` + - `frontend/src/app/features/admin/challenges/challenge-form-modal.component.ts:404` + - `frontend/src/app/features/admin/challenges/challenge-delete-modal.component.ts:56` + - `frontend/src/app/features/landing/landing.component.ts:102` + - The very similar `change-password-modal.component.ts:156–159` guards the handler with `if (this.open() && !this.submitting()) this.onCancel();`. We will mirror that exact contract for the blog form modal (swapping `submitting()` for `saving()`). + - **The blog form modal is the only modal missing this listener.** This is the bug described in the Job. +- **Data Layer:** No database changes — this is purely a frontend modal interaction fix. +- **Test Framework & Structure:** + - Jest 29 with `ts-jest`, frontend project runs in `jsdom` (`tests/jest.config.js`). + - Single test entry: `npm test` runs both backend and frontend projects; `npm run test:frontend` runs only frontend. + - Tests live under `tests/frontend/` (front-end) and `tests/backend/` (back-end). Source code lives under `frontend/src/app/` and `backend/src/`. Tests must NEVER live inside source folders. + - Existing frontend tests are predominantly pure-helper tests (no TestBed). The `challenge-card-accessibility.spec.ts` pattern uses a `readFileSync` source-text assertion against the component template, which is the safest pattern for testing that a `@HostListener` is wired into the component without standing up the full Angular runtime. +- **Required Tools & Dependencies:** None. No new packages, globals, or `setup.sh` changes are needed — `@angular/core` already exports `HostListener`, and Jest/jsdom is already configured. + +## 2. Impacted Files + +- **To Modify:** + - `frontend/src/app/features/admin/blog/blog-form-modal.component.ts` — add the `@HostListener('document:keydown.escape')` handler that calls the existing `onCancel()` when the modal is open and not currently saving. +- **To Create:** + - `tests/frontend/blog-form-modal-escape.spec.ts` — minimal, focused regression test that verifies the Escape listener is wired and routed correctly. Mirrors the existing source-text snapshot pattern from `tests/frontend/challenge-card-accessibility.spec.ts` so it stays free of TestBed/Angular runtime setup and runs instantly under `npm test`. + +## 3. Proposed Changes + +1. **Add an Escape handler to `BlogFormModalComponent`** in `frontend/src/app/features/admin/blog/blog-form-modal.component.ts`: + - Import `HostListener` from `@angular/core` alongside the existing `ChangeDetectionStrategy`, `ChangeDetectorRef`, `Component`, `DestroyRef`, `effect`, `inject`, `input`, `output`, `signal` imports. + - Add the following method on the class (mirroring `change-password-modal.component.ts:156–159`): + ```ts + @HostListener('document:keydown.escape') + onEscape(): void { + if (this.open() && !this.saving()) this.onCancel(); + } + ``` + - This reuses the existing `onCancel()` (`blog-form-modal.component.ts:210`) which already emits `cancel`. The parent `AdminBlogComponent.closeModal()` (`blog.component.ts:188`) clears `modalMode`, `editing`, `formError`, `saving`, etc., so no post is created or modified. + - Rationale for the `open() && !saving()` guard: the modal is conditionally rendered via `@if (open())` in the template, so the listener will fire when the modal is mounted regardless of `open()`'s value; we explicitly check `open()` for safety and parity with `change-password-modal.component.ts`, and we skip the handler while `saving()` is true so an in-flight create/publish cannot be cancelled mid-request (the existing `Publish`/`Save draft` buttons remain `[disabled]` while saving and the parent also blocks the toolbar via `actionInFlight`). + - No template, styles, or HTML attribute changes are needed. The `Cancel` button, backdrop click, and the new Escape keypress all flow through the same `onCancel()` → `cancel` output. + +2. **No backend / API changes.** The bug is purely a missing keyboard handler on the client. The REST endpoints (`POST /api/v1/admin/blog/posts`, `PATCH /api/v1/admin/blog/posts/:id`) are already correct; the failing test scenario was a *frontend* interaction that never called the API. + +3. **No `setup.sh` / dependency changes.** `HostListener` is part of `@angular/core`, which is already a dependency. + +## 4. Test Strategy + +- **Target Unit Test File:** `tests/frontend/blog-form-modal-escape.spec.ts` (new file, in the dedicated `tests/frontend/` folder, runnable via `npm test` from the repo root). +- **Mocking Strategy:** No runtime mocking required. The test uses the same source-text assertion pattern as `tests/frontend/challenge-card-accessibility.spec.ts`: read `frontend/src/app/features/admin/blog/blog-form-modal.component.ts` once with `fs.readFileSync` and assert that: + 1. `HostListener` is imported from `@angular/core` (presence of the symbol in the import block). + 2. The exact decorator `@HostListener('document:keydown.escape')` is present on the class. + 3. The decorated handler method calls `this.onCancel()`. + 4. The handler is guarded by `this.open()` and `this.saving()` (to prevent Escape from cancelling an in-flight save, matching the `change-password-modal` contract). + 5. The existing `onCancel()` method still emits `cancel` (regression guard that the wiring remains intact). +- The test must import `'@angular/compiler'` at the top for parity with the rest of the frontend suite (see `tests/frontend/blog-admin-form.spec.ts:1`). +- Avoid standing up TestBed, ComponentFixture, or any DOM/jest-environment-jsdom behavior — keep the test pure and instant, per the `IMPORTANT RULE CONCERNING TESTS` instructions. +- All tests must pass via `npm test` (or `npm run test:frontend`) inside the container without any UI/browser interaction. diff --git a/docs/architecture/frontend-structure.md b/docs/architecture/frontend-structure.md index 125abc2..bf7c5f9 100644 --- a/docs/architecture/frontend-structure.md +++ b/docs/architecture/frontend-structure.md @@ -50,7 +50,7 @@ Routes live in `frontend/src/app/app.routes.ts`: | `BlogPage` | `frontend/src/app/features/blog/blog.page.ts` | Smart `/blog` page that loads published posts and derives loading, error, empty, and list states. | | `BlogPresenterComponent` | `frontend/src/app/features/blog/blog-presenter.component.ts` | Shared title/date/sanitized-Markdown renderer used by `/blog` and `/login`. | | `AdminBlogComponent` | `frontend/src/app/features/admin/blog/blog.component.ts` | Smart `/admin/blog` page coordinating list refresh and create/edit/delete modal state. | -| `BlogFormModalComponent` / `BlogDeleteModalComponent` | `frontend/src/app/features/admin/blog/` | Admin Markdown editor with live preview and destructive-action confirmation. | +| `BlogFormModalComponent` / `BlogDeleteModalComponent` | `frontend/src/app/features/admin/blog/` | Admin Markdown editor with live preview and destructive-action confirmation. `BlogFormModalComponent` also installs a `@HostListener('document:keydown.escape')` handler that closes the modal via `onCancel()` when the modal is open and not currently saving (mirrors the `change-password-modal` Escape contract). | # Authenticated SSE wiring diff --git a/docs/guides/blog.md b/docs/guides/blog.md index ba0e626..10add9b 100644 --- a/docs/guides/blog.md +++ b/docs/guides/blog.md @@ -3,7 +3,7 @@ type: guide title: Blog Publishing and Reading description: How administrators create, edit, publish, and delete Markdown posts and how users read published posts. tags: [guide, blog, admin, markdown, tester] -timestamp: 2026-07-23T10:12:24Z +timestamp: 2026-07-23T10:36:45Z --- # User views @@ -34,6 +34,14 @@ Both views use `BlogPresenterComponent` to show the post title, publication date * Click the trash action to open **Delete post**. The confirmation includes the title and warns that deletion cannot be undone. * Click **Delete** to remove the post. The table refreshes and displays `Post deleted.`. Click **Cancel** or the modal backdrop to leave the post unchanged. +# Closing modals with Escape + +Both the **New post / Edit post** modal and the **Delete post** confirmation honor the platform-wide Escape-to-close convention: + +* Pressing **Escape** while the modal is open closes it without saving or deleting. +* Escape is suppressed while a save/publish request is in flight (the modal stays open until the current operation completes), so an in-flight create or update cannot be silently cancelled by an accidental keypress. +* Escape, the **Cancel** / **Delete** buttons, and clicking the modal backdrop all close the modal via the same `onCancel()` → `cancel` output flow; no partial post is ever created or modified when Escape is pressed. + # Validation and expected errors | Input or operation | Expected behavior | diff --git a/docs/index.md b/docs/index.md index 2b8c2de..06d600b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,7 +12,7 @@ controls, administrator-managed Markdown blog publishing, and public and signed-in blog views. The docs below are organized by purpose so agents can pull just the slice -they need. Last regenerated 2026-07-23T10:12:24Z. +they need. Last regenerated 2026-07-23T10:36:45Z. # Architecture diff --git a/frontend/src/app/features/admin/blog/blog-form-modal.component.ts b/frontend/src/app/features/admin/blog/blog-form-modal.component.ts index 1b22d1f..28355d9 100644 --- a/frontend/src/app/features/admin/blog/blog-form-modal.component.ts +++ b/frontend/src/app/features/admin/blog/blog-form-modal.component.ts @@ -3,6 +3,7 @@ import { ChangeDetectorRef, Component, DestroyRef, + HostListener, effect, inject, input, @@ -211,6 +212,11 @@ export class BlogFormModalComponent { this.cancel.emit(); } + @HostListener('document:keydown.escape') + onEscape(): void { + if (this.open() && !this.saving()) this.onCancel(); + } + onSubmit(action: 'draft' | 'publish'): void { this.titleTouched.set(true); this.bodyTouched.set(true); diff --git a/tests/frontend/blog-form-modal-escape.spec.ts b/tests/frontend/blog-form-modal-escape.spec.ts new file mode 100644 index 0000000..a13caf3 --- /dev/null +++ b/tests/frontend/blog-form-modal-escape.spec.ts @@ -0,0 +1,67 @@ +import '@angular/compiler'; +import { readFileSync } from 'node:fs'; +import { resolve } from 'node:path'; + +const sourcePath = resolve( + __dirname, + '../../frontend/src/app/features/admin/blog/blog-form-modal.component.ts', +); +const source = readFileSync(sourcePath, 'utf8'); + +describe('BlogFormModalComponent — Escape-to-close contract', () => { + it('imports HostListener from @angular/core', () => { + const importBlock = source.match( + /import\s*\{[\s\S]*?\}\s*from\s*'@angular\/core';/, + ); + expect(importBlock).not.toBeNull(); + expect(importBlock![0]).toMatch(/\bHostListener\b/); + }); + + it('registers a @HostListener for document:keydown.escape', () => { + expect(source).toMatch( + /@HostListener\(\s*['"]document:keydown\.escape['"]\s*\)/, + ); + }); + + it('guards the Escape handler with open() so a closed modal is a no-op', () => { + const handler = extractEscapeHandler(source); + expect(handler).not.toBeNull(); + expect(handler).toMatch(/this\.open\(\)/); + }); + + it('guards the Escape handler against in-flight saves (no cancel while saving)', () => { + const handler = extractEscapeHandler(source); + expect(handler).not.toBeNull(); + expect(handler).toMatch(/!this\.saving\(\)/); + }); + + it('routes Escape to the existing onCancel() so the parent closes the modal without saving', () => { + const handler = extractEscapeHandler(source); + expect(handler).not.toBeNull(); + expect(handler).toMatch(/this\.onCancel\(\)/); + }); + + it('keeps the existing onCancel() emit intact as a regression guard', () => { + const onCancel = extractMethod(source, 'onCancel'); + expect(onCancel).not.toBeNull(); + expect(onCancel).toMatch(/this\.cancel\.emit\(\s*\)/); + }); +}); + +function extractEscapeHandler(src: string): string | null { + // Capture the onEscape handler body — must contain the guard + onCancel call. + const m = src.match( + /@HostListener\(\s*['"]document:keydown\.escape['"]\s*\)\s*onEscape\s*\(\s*\)\s*:\s*void\s*\{([^}]*)\}/, + ); + return m ? m[1] : null; +} + +function extractMethod(src: string, name: string): string | null { + const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); + // Match the method header (with optional TypeScript return-type annotation) and capture the body. + const re = new RegExp( + `(?:public\\s+|private\\s+|protected\\s+)?${escaped}\\s*\\([^)]*\\)\\s*(?::\\s*[A-Za-z_<>|[\\]\\s,]+)?\\s*\\{([\\s\\S]*?)\\n\\s*\\}`, + ); + const m = src.match(re); + return m ? m[1] : null; +}