CMS: één bannerlijst met Locatie, SLP-thema, thema-schakelaar, documentatie

- Banner-admin: één lijst met Locatie-badge (Boven/Onder), Locatie-keuzeveld in het formulier, "Live" en "Wordt niet getoond" per locatie, aan/uit per rij
- Thema slpsoftware: Archivo, bordeaux #7A1414 (WCAG AA licht en donker), <SLP/>-logo, favicon, mail-logo; VITE_THEME in de SLP-builds (test en productie-config)
- Thema-schakelaar: eerste klik wisselt altijd het getoonde thema (klasse op <html> als bron van waarheid, gedeelde status, startscript valideert opslag) + tests
- Docs: README, docs/cms-themas.md, docs/deploy-en-testomgevingen.md, docs/privacy-gegevens-contactformulier.md, aidlc-docs (offering-banners, bug theme-toggle-first-click)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-15 00:14:10 +01:00
co-authored by Claude Sonnet 5.5
parent 4b09089ffb
commit 321234dfa6
28 changed files with 1081 additions and 242 deletions
+2
View File
@@ -17,3 +17,5 @@
| Bug | [availability-gate-blocks-website-and-admin](bugs/availability-gate-blocks-website-and-admin/bug-fix.md) | ✅ Complete (gemerged via PR #11, 2026-11-10) | feature/identity-email-notifications | Availability (middleware) | 2026-11-09 |
| Bug | [setup-page-after-failed-status-read](bugs/setup-page-after-failed-status-read/bug-fix.md) | ✅ Complete (gemerged via PR #11, 2026-11-10) | feature/identity-email-notifications | Frontend (router guard, login), Identity (Setup limiter) | 2026-11-09 |
| Feature | Contact Forms Module (contact-forms-module) | 🟡 Construction fase 2 (CMS-U7 en U5 klaar; U6, U8 volgen; niets gepusht) | feature/contact-forms-module | Modules (new Contact + Tests, Offerings category), Core (OnRejected, availability gate marker), Frontend (admin Berichten) | 2026-11-09 |
| Feature | [Offering banners (offering-banners)](features/offering-banners/overview.md) | 🟡 Op test (buiten AI-DLC gebouwd en achteraf gedocumenteerd; admin-lijst met Locatie-badge op test sinds 2026-11-15) | feature/contact-forms-module | Modules.Offerings (banner met positie top/bottom), openapi, Frontend (admin Aanbiedingen > Banner) | 2026-11-12 |
| Bug | [theme-toggle-first-click](bugs/theme-toggle-first-click/bug-fix.md) | ✅ Complete (niet gecommit/gemerged; buiten AI-DLC gebouwd; oorzaak niet in een echte browser nagebootst) | feature/contact-forms-module | Frontend (useTheme, index.html) | 2026-11-15 |
@@ -0,0 +1,43 @@
# Bug Fix: the first click on the theme toggle does nothing
- **Slug**: theme-toggle-first-click
- **Status**: Complete (pending deploy; built outside the AI-DLC flow, documented afterwards)
- **Issue**: None (reported by Bryan)
- **Branch**: feature/contact-forms-module
- **Started**: unknown
- **Documentation Language**: English
- **Conversation Language**: Dutch (user language)
## Report
In the admin, the first click on the light/dark toggle sometimes changed nothing visible; only the second click switched the theme.
## Root Cause
The `useTheme` hook (`frontend/src/hooks/useTheme.ts`) kept its own state, initialised from `localStorage` (`cms-theme`) or else from the OS preference (`prefers-color-scheme`). What is actually shown is decided by the class (`light` / `dark`) on `<html>`, which the start script in `frontend/index.html` sets before React runs. The two were not the same source: when the hook's state and the class on `<html>` differed, the first click flipped the hook's state and applied *that* theme, which could be the theme already shown, so nothing visible happened.
Two ways they could differ, both visible in the old code:
1. The start script in `index.html` took any stored value as a class name (`s ? s : ...`), while the hook only accepted `light` or `dark`. A stored value such as `system` put the class `system` on `<html>` (no theme at all) while the hook fell back to the OS preference.
2. Every toggle (desktop sidebar, mobile overlay) called `useTheme()` and so had its own state; flipping one left the others stale, so the next click on another toggle could re-apply the theme already shown.
**Not reproduced in a real browser.** The cause was derived from reading the old code; the only evidence is that the new tests fail against the old hook (reported by the developer; not re-run for this document). Which of the two cases (or another) happened in the browser session that was reported is not known.
## The Fix
- `useTheme.ts`: one source of truth, the class on `<html>`, read through `useSyncExternalStore`. If the page carries neither class, the stored value or OS preference is applied right away, so the reported state and what is shown cannot differ. `toggleTheme` flips what is shown now, stores it (inside `try/catch`, since storage can be unavailable), applies it and notifies every subscriber, so all toggles on the page share one state.
- `index.html`: the start script accepts only `light` or `dark` from storage; anything else falls back to the OS preference.
## Verification
**Path used**: Automated test framework (`frontend/src/hooks/useTheme.test.ts`, new block `first click`, 4 tests): with the OS preferring light and with it preferring dark and nothing stored or applied, the first click flips the shown theme; an unusable stored value (`system`) with class `system` on `<html>` still flips from what is shown; when the shown theme differs from the stored one the toggle follows the shown one and stores the new value; two toggles on one page stay in step.
**Before the fix**: according to the developer, the new tests fail against the old hook. Not re-run for this document. **After the fix**: not re-run for this document either.
**Not verified**: behaviour in a real browser (no manual reproduction before or after the fix).
## Result
- **PR(s)**: None
- **Commit(s)**: commit "CMS: één bannerlijst met Locatie, SLP-thema, thema-schakelaar" on feature/contact-forms-module (2026-11-15)
- **Completed**: 2026-11-15 (documentation)
@@ -510,6 +510,7 @@ change:
| `PI_MAIN_PORT` | secret | SSH port |
| `PI_MAIN_USERNAME` | secret | `gitea-workflow` — the generic, host-wide deploy account (§ 1.2), **not** `webadmin`; reuse the reference project's if it already has one |
| `PI_MAIN_PASSWORD` | secret | `gitea-workflow`'s password |
| `PI_MAIN_SSH_KEY` | secret | Optional: private key of the deploy account. When set and accepted, `deploy-scp.yaml` uses it instead of the password (needed for runners the host does not allow password login from) |
| `DEPLOY_PATH_TEST` | variable | `/home/gitea-workflow/apps/slpsoftware/test` |
| `DEPLOY_PATH_PRODUCTION` | variable | `/home/gitea-workflow/apps/slpsoftware/production` |
| `SERVICE_NAME_TEST` | variable | `slpsoftware-test.service` |
@@ -525,11 +526,13 @@ change:
## 2. Deploy Sequence (What Actually Happens on a Run)
Current compact overview, including the ASF test jobs and deploying a branch: `docs/deploy-en-testomgevingen.md` (checked against the workflows on 2026-11-15).
Already built (U5/U6) — this is the read-only walkthrough for whoever operates it:
1. Push to `master`, or a manual `workflow_dispatch` → the six gates run
2. `publish-test` runs (and `publish-production`, only if `workflow_dispatch` with the flag)
3. `deploy-test` (always, if gates pass) calls `deploy-scp.yaml`, which uploads into a new
1. Push to `master`, or a manual `workflow_dispatch` (inputs `deploy_test`, `deploy_production`, `deploy_asf_test`, all off by default) → the gates run (`changes`, `backend-build`, `backend-test`, `vulnerability-scan`, `frontend-prepare`, `frontend-build`, `frontend-test`, `frontend-lint`)
2. `publish-test` runs on a push to `master`, on pull requests (build only, no deploy) and on a dispatch with `deploy_test`; `publish-production` only on a dispatch with `deploy_production`
3. `deploy-test` (on a push to `master`, or a dispatch with `deploy_test`; not on pull requests) calls `deploy-scp.yaml`, which uploads into a new
`releases/{timestamp}/`, links `shared/wwwroot-web` and any `shared/modules/*.dll` in, switches
`current`, restarts `slpsoftware-test.service`, verifies `https://test.slpsoftware.nl/health`,
then prunes old releases (only test — `run_db_backup: false`)
@@ -0,0 +1,83 @@
# Offering Banners (offering-banners)
- **Slug**: offering-banners
- **Type**: Feature (small), built outside the AI-DLC flow and documented afterwards
- **Status**: On test (not merged, not pushed)
- **Branch**: feature/contact-forms-module
- **Affected components**: `SlpModularCms.Modules.Offerings` (+ Tests), openapi/slpsoftware.v1.json, frontend admin (`frontend/src/features/offerings`)
- **Documented**: 2026-11-15
- **Documentation Language**: English
- **Conversation Language**: Dutch (user language)
> This feature was **not** run through the AI-DLC stages (no requirements, design or audit trail). This file records what the code does, checked against the code on 2026-11-15. There are no `requirements`, `plans` or `audit.md` for it.
## Purpose
A site-wide, schedulable announcement ("banner") for offers and campaigns, managed by administrators in the CMS and fetched by the website through one public endpoint. A banner has a **position**: `top` (a narrow one-line bar above the page) or `bottom` (the large banner, which is also what every banner was before positions existed).
## History
| Commit | What |
|---|---|
| a2f4513 (2026-11-12) | `OfferingBanner` entity, `GET /offerings/banner`, banner layout removed (backend) |
| 5386abb (2026-11-12) | Banner tab in the admin (list, form, schedule); layout removed from the frontend |
| 4b09089 (2026-11-14) | Position `top`/`bottom` (backend, migration, admin tab, OpenAPI) |
| 2026-11-15 (commit "CMS: één bannerlijst met Locatie, SLP-thema, thema-schakelaar", on test) | Admin list: one list with a Location badge, "Live" / "Not shown" markers, on/off toggle per row; Location field in the form (`OfferingBannersTab.tsx`, `OfferingBannerDialog.tsx`, translations) |
## Contract
Routes are served under `/api/v1` (like all module routes).
### Public: `GET /api/v1/offerings/banner?position=top|bottom`
Source: `Controllers/OfferingBannersController.cs` (`PublicOfferingBannerController`).
| Aspect | Behaviour |
|---|---|
| Authentication | Anonymous (`[AllowAnonymous]`, `[PublicSiteEndpoint]`: stays reachable through the availability gate) |
| `position` | Optional. Absent or empty = `bottom`. Any other value than `top` / `bottom` (case sensitive) = `400` with `{ "error": "Position must be 'top' or 'bottom'." }` |
| No active banner at that position | `204 No Content` |
| Active banner | `200` with `{ title, text, linkLabel, linkUrl, position }` (no scheduling fields, no id) |
| Caching | `Cache-Control: public, max-age=60` is set on every answer that gets past the position check (so 200 and 204; not on the 400) |
| Rate limit | Policy `offerings-public`: fixed window per client address, `RateLimiting:OfferingsPublic:PermitLimit` / `WindowSeconds`, default 120 per 60 s (`ServiceCollectionExtensions.cs`); beyond it `429` |
### Management: `/api/v1/offerings/banners` (policy `AdminOnly`, i.e. role Administrator or higher)
| Method and route | Result |
|---|---|
| `GET /offerings/banners` | `200` list of all banners, most recently changed first (`id, position, title, text, linkLabel, linkUrl, isActive, startsAt, endsAt, updatedAt`) |
| `POST /offerings/banners` | `201` with the banner |
| `PUT /offerings/banners/{id}` | `200` with the banner (full replace), `404` if unknown |
| `DELETE /offerings/banners/{id}` | `204`, `404` if unknown |
### Fields and validation (`Models/OfferingBannerModels.cs`, `Data/Entities/OfferingBanner.cs`)
| Field | Rule |
|---|---|
| `position` | `top` or `bottom`; default `bottom` |
| `title` | Max 100 characters. **Required for `bottom`**, optional for `top` (may be empty) |
| `text` | Required, max 300 characters (`MaxLength`). For `top` the trimmed text is max **120** characters |
| `linkLabel` (max 50) and `linkUrl` (max 500) | Both or neither. Empty values are stored as null |
| `linkUrl` form | An `https://` URL with a host, or a site path starting with a single `/`. Not allowed: `//host`, backslashes, whitespace or control characters |
| `isActive` | Default `true` |
| `startsAt`, `endsAt` | Optional; if both are given, `endsAt` must be after `startsAt` |
Text fields are trimmed before storage. Every change logs `Offering banner {id} {Created|Updated|Deleted} by user {id}` and invalidates the `IIndexHtmlCache` when one is registered (`OfferingBannersService.Changed`). Whether a banner is injected into any HTML through that cache is not verified (no reference to banners was found in `Core/Hosting/Website`).
### Database
Table `OfferingsBanners`. Migration `20261114100000_AddOfferingBannerPosition` adds `Position varchar(10) NOT NULL DEFAULT 'bottom'`, so **every banner that existed before becomes `bottom`**. (Earlier migration `20261112100000_AddOfferingBannerRemoveLayout` created the table and dropped the `Layout` column of `OfferingsOfferings`.)
## Decisions (as implemented)
1. **"At most one per position" is enforced when reading, not when saving.** Any number of banners can be stored and switched on. `GetActiveAsync(position)` takes the banners that are switched on, at that position, inside their schedule (`StartsAt <= now` and `now < EndsAt`, either may be empty), and returns the one with the latest `UpdatedAt`. A top and a bottom banner can therefore be shown at the same time.
2. **The schedule is evaluated on the server at request time** (UTC, via `TimeProvider`); the browser's time zone only matters in the admin form (datetime-local, converted to UTC).
3. **The admin shows one list for both positions**, not one tab per position: a Location badge on each row (Top / Bottom), a status badge (Active / Planned / Expired / Off), and a "Live" badge on the banner visitors see now. An active banner shadowed by a more recently changed one at the same position gets "Not shown" plus a hint. `shownBannerIds` in `OfferingBannersTab.tsx` is a client-side copy of the server rule, not a server field. Each row has an on/off button (re-sends the banner through `PUT` with `isActive` flipped).
4. **The form follows the position**: changing Location changes the text limit (120 / 300) and whether the title is optional; the limits are mirrored in `schemas/offeringBanner.ts`.
5. **Links are restricted to `https://` or own-site paths**, which excludes `javascript:` and protocol-relative links.
## Known gaps and notes
- The OpenAPI document (`openapi/slpsoftware.v1.json`) describes the public endpoint with only a `200` answer: no `204`, `400` or `429`, no response body schema, no allowed values for `position`. The request schema has no length limits and no enum for `position`; `POST` is documented as `200` while the code returns `201`. The controllers carry no `[ProducesResponseType]` annotations. Not changed here.
- The website that shows the banner is not in this repository; how it fetches and renders the banner is not verified. The admin hint says that for Andrea's website the schedule applies at the next (nightly) build; that build is not in this repository either (not verified).
- Hosts that expose the module: `Api.SlpSoftware` and `Api.AndreaSlopFotografie` reference `Modules.Offerings` (csproj); the dev host `Api` does not.