Docs: hero zonder planning en hero-brede aan/uit (FR-05, BR-H07/BR-P01, aannamelijst 30, contract)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-17 08:21:42 +01:00
co-authored by Claude Sonnet 5.5
parent b78e890f65
commit 555ab10e14
5 changed files with 6 additions and 5 deletions
@@ -34,3 +34,4 @@ Kept while Bryan was away (2026-11-16): no questions to him, a likely assumption
| 28 | **The focus dialog showed a stretched photo** for any photo that is not 3:2: it used the published wide crop (`image.src`) as if it were the whole photo. | Every set now also holds a full-frame preview (`full-<width>.webp`, the whole picture at its own shape, at most 1280 wide); the admin API gives it as `previewSrc`, it is not in `variants` and not published to websites. Sets made before it existed get only that file added by the background renderer (not shown as processing, no address changes). | Without a preview yet the dialog says so instead of showing a wrong picture. | `VariantPlanner.Preview`, `HeroMapping.PreviewSrc`, `FocusDialog` |
| 29 | **A photo could stay "processing" for ever** in the admin: a photo that was uploaded but not saved yet only had the state of the upload response. | The page now asks the server for those photos one by one (`GET /api/v1/hero/images/{id}`, every 5 s while processing, also in a background tab); each photo shows its own state and, when done, a short "Processing finished" note on that photo (no toast). A photo that was already in the CMS (`reused`, internal only) looks the same and is ready at once. | n/a | `heroImageQuery`, `DoneStatus` |
| 30 | **Planning (from/to) and the hero-wide on/off are gone** (Bryan, 2026-11-17): the hero is part of the design and always on; a planning per slide became too much trouble. | Removed from model, API (PUT/GET, OpenAPI), validation, host logic (`IsLive` = has a title), admin (fields, nl/en texts) and tests; migration `RemoveHeroScheduleAndSwitch` drops `StartsAt`, `EndsAt` and `IsActive` of the hero (the per-slide `IsActive` stays). The public JSON, golden files and both sites did not depend on them. Without hero data the host writes nothing. | Planning can be added later, probably per slide; a hero-wide switch likewise. | `HeroMapping.IsLive`, migration `RemoveHeroScheduleAndSwitch` |
@@ -12,7 +12,7 @@ IDs are used in the code, tests and the build and test summary.
| BR-H04 | `display` is `single` or `slideshow`; default `single`; any other value is rejected. |
| BR-H05 | 0 to 2 buttons. Both `label` (1 to 50 characters) and `target` (at most 500) are required for a button; a half-filled button is rejected. |
| BR-H06 | A target is exactly one of: **anchor** `#` followed by a letter and then letters, digits, `-` or `_` (at most 100 characters); **path** starting with a single `/` (not `//`), no `\`, no control characters, no whitespace, no `:` before the first `/`; **https address** with the scheme `https`, a host, no user info, parsed as an absolute URI. Anything else is rejected with the message "Kies een #anker, een /pad of een https://-adres." |
| BR-H07 | Schedule: `startsAt` and `endsAt` optional; when both exist `endsAt` must be after `startsAt`. Stored in UTC; displayed in the admin in local time. |
| BR-H07 | **Removed 2026-11-17 (no schedule, no hero-wide switch; see FR-05).** Was: Schedule: `startsAt` and `endsAt` optional; when both exist `endsAt` must be after `startsAt`. Stored in UTC; displayed in the admin in local time. |
| BR-H08 | Text in every field is plain text. The server stores it as typed (control characters other than the line break are removed) and encodes it when writing HTML (`& < > " '`) and JSON in a script element (`< > &` and U+2028/2029 as `\uXXXX`). No field can produce markup or script. |
| BR-H09 | Slides: no administrator limit on the number. Each slide has an existing image, `alt` (at most 300 characters) or `decorative = true`, an order, and `isActive`. A slide that is not decorative needs a non-empty alt to be saved. `decorative` and a non-empty alt together are accepted; the alt is then ignored when published. |
| BR-H10 | Technical safety ceiling: at most `Hero:MaxPublishedSlides` (default 50) slides are published; the rest stay saved. Reported to Bryan (see the logic model). |
@@ -23,7 +23,7 @@ IDs are used in the code, tests and the build and test summary.
| ID | Rule |
|---|---|
| BR-P01 | The public hero exists only when the hero `isActive`, now is within the schedule (start inclusive, end exclusive), the title is non-empty. Otherwise 204 and the baked hero stays. |
| BR-P01 | **Since 2026-11-17 the hero exists as soon as it has a title (no switch, no schedule); the rest below still holds for slides.** Was: The public hero exists only when the hero `isActive`, now is within the schedule (start inclusive, end exclusive), the title is non-empty. Otherwise 204 and the baked hero stays. |
| BR-P02 | Only active slides with a stored image are published, in saved order. |
| BR-P03 | `GET /api/v1/hero` answers with `Cache-Control: public, max-age=60`, rate-limited (policy `hero-public`, 120 per 60 s), anonymous, through the availability gate. |
| BR-P04 | The HTML region, the preload and the data block are derived from the same read model per request cycle. |
@@ -57,7 +57,7 @@
| FR-02 | Fields: `title` (required, one text, new lines allowed, max 200 chars), `tagline` (optional, max 120), `lead` (optional, max 600), `display` (`single` or `slideshow`, default `single`). Plain text only; the host and the sites encode it. |
| FR-03 | 0 to 2 buttons, each with `label` (max 50) and `target` (max 500). Both required per button. Target must match exactly one of: `#anchor` (letters, digits, `-`, `_`), a site path starting with a single `/` (no `//`, no scheme, no backslash, no control characters), or an absolute `https://` address with a host and no credentials. Anything else is rejected with a clear message. |
| FR-04 | 0 to n slides, each with: stable `id`, one image, `alt` text (required, max 300, or an explicit `decorative` flag instead), `order`, `isActive`. Inactive slides are not published. A reasonable maximum (for example 12) protects the page weight. |
| FR-05 | Schedule: optional `startsAt` / `endsAt` for the hero as a whole (as banners). Outside the period the hero counts as not available (204). |
| FR-05 | ~~Schedule~~ **Removed (Bryan, 2026-11-17).** No `startsAt`/`endsAt` and no hero-wide on/off (`isActive`): the hero is part of the design and always on; it is live as soon as it has a title, and without hero data the host writes nothing (the baked hero stays). Per-slide on/off stays. A schedule may come back later, then probably per slide. |
| FR-06 | Text fields and slide data are stored so that a language can be added later without migrating existing rows (for example a language key or a translations structure with the current language as the default); only one language is exposed and edited now. |
| FR-07 | Management needs role Administrator or higher (policy `AdminOnly`); the public read endpoint is anonymous and reachable through the availability gate (like the banner). |
@@ -13,7 +13,7 @@ Input for Application Design. Source: message of "Andrea Slop Fotografie - ASF -
| Lead | ASF does not render it; if present the site ignores it. |
| Decorative | `decorative: true` renders `alt=""` and is not read aloud. |
| Display | `single`: no arrows, pause button or progress bar (ASF already does that for one slide). |
| 204 / schedule / error | The baked hero stays (fail-open). ASF shows the baked hero on 204, not nothing. If the host ever means "no hero at all", that must be said explicitly (not planned). |
| 204 / no hero data / error | The baked hero stays (fail-open). ASF shows the baked hero on 204, not nothing. If the host ever means "no hero at all", that must be said explicitly (not planned). |
| Image addresses | Same origin `/media/hero/<hash>/…`, immutable; the CSP `img-src` does not change. |
| Markers | `<!--CMS:HERO-HTML-->…<!--/CMS:HERO-HTML-->` (title, tagline, button(s), the FIRST slide as `<picture>`), `<!--CMS:HERO-PRELOAD-->` in the head, key `hero` in `#cms-data` with all slides. Fail-open: no marker, 204 or an error leaves the baked page. |
| Hydration | The region holds neutral HTML (fixed classes, no Chakra classes); React takes over with the same source after hydration; slides 2..n load afterwards. The first slide of the data block must equal the first slide the host wrote into the HTML (same source, same cache rule). |