77 lines
8.9 KiB
Markdown
77 lines
8.9 KiB
Markdown
# Components: hero-module
|
|
|
|
Namespaces follow the existing modules (`SlpModularCms.Core.*`, `SlpModularCms.Modules.Hero`). "New" = created in this feature, "Changed" = existing code that is adapted.
|
|
|
|
## C1. `SlpModularCms.Modules.Hero` (New, the module)
|
|
|
|
| Component | Purpose and responsibilities |
|
|
|---|---|
|
|
| `HeroModule` (`IModule`) | Registers services, DbContext, texts (`AddCmsTextsFrom`), the HTML transform, the preload marker provider and the data contributor; runs the module's migrations. Name `Hero`, switched on or off per site by the project references and committed defaults (like Offerings). |
|
|
| `HeroDbContext` + entities | Tables `Heroes`, `HeroSlides`, `HeroImages` (see data model below). Own migrations, same style as the Offerings migrations (hand-written, MySQL). |
|
|
| `IHeroRepository`, `IHeroImageRepository` | Persistence of the hero with its slides, and of the images with their variant lists. |
|
|
| `IHeroService` | Management use cases: read and save the hero (texts, buttons, display, schedule, slide list and order), validation, change notification. |
|
|
| `IHeroImageService` | Upload, replace and remove of an image: validates and processes through the media service, stores the files, writes the metadata, changes focus/zoom per ratio (regenerates the variants), removes orphans. |
|
|
| `IPublicHeroService` | The read model for sites: the active hero (schedule and active slides applied) as `PublicHeroDto`, or null. Used by `GET /hero`, the HTML transform and the data contributor, so all three show exactly the same thing. |
|
|
| `HeroController` | Public read `GET /api/v1/hero` (anonymous, `[PublicSiteEndpoint]`, `public, max-age=60`, rate-limit policy `hero-public`, 204 when there is no active hero); management `GET /api/v1/hero/all` (the full hero including inactive slides and the schedule) and `PUT /api/v1/hero` (policy `AdminOnly`). Same convention as `offerings` and `offerings/all`. |
|
|
| `HeroImagesController` (admin) | `POST /api/v1/hero/images` (multipart upload, size limit), `PUT /api/v1/hero/images/{id}/focus`, `DELETE /api/v1/hero/images/{id}`. |
|
|
| `ButtonTargetValidator` | Pure function: accepts `#anchor`, `/path`, `https://host/...`, rejects everything else. |
|
|
| `HeroHtmlTransform` (`IHtmlPageTransform`) | Fills `<!--CMS:HERO-HTML-->` regions: title lines, tagline, buttons and the first active slide as `<picture>`. Fail-open. |
|
|
| `HeroPreloadMarkerProvider` (`IIndexHtmlMarkerProvider`) | Writes the one or two `<link rel="preload" as="image">` elements at `<!--CMS:HERO-PRELOAD-->`; shares the `srcset`/`sizes`/`media` generator with the transform so they are byte-for-byte equal. |
|
|
| `HeroPictureRenderer` | Pure: one place that produces the `<picture>`/`<img>` attributes and the preload attributes from a `PublicHeroDto`; golden-tested. |
|
|
| `HeroDataContributor` (`ICmsDataBlockContributor`) | Adds the key `hero` (the `PublicHeroDto`, or null) to the data block. |
|
|
| `HeroTexts` + `Texts/nl.json`, `en.json` | Backend texts (validation messages) per `docs/translation-files.md`. |
|
|
|
|
### Data model (sketch, detailed in Functional Design)
|
|
|
|
| Entity | Fields |
|
|
|---|---|
|
|
| `Hero` | `Id`, `Language` (default `nl`; unique per language so a language can be added later without migrating rows), `Title` (text with line breaks), `Tagline`, `Lead`, `Display` (`single`/`slideshow`), `Button1Label/Target`, `Button2Label/Target`, `StartsAt`, `EndsAt`, `IsActive`, `UpdatedAt`, `UpdatedBy` |
|
|
| `HeroSlide` | `Id` (GUID, stable), `HeroId`, `ImageId`, `Alt`, `Decorative`, `SortOrder`, `IsActive` |
|
|
| `HeroImage` | `Id`, `OriginalKey` (store key), `Sha256`, `SourceFormat`, `Width`, `Height`, `Bytes`, `Focus` (general, default centre: `X`, `Y`, `Zoom`), optional `WideFocus` and `TallFocus` (`X`, `Y`, `Zoom`, nullable), `VariantSetHash`, `VariantsJson` (list of `{ratio, width, type, key, bytes}`), `CreatedAt` |
|
|
|
|
## C2. `SlpModularCms.Core.Media` (New, general media service in Core)
|
|
|
|
| Component | Purpose and responsibilities |
|
|
|---|---|
|
|
| `IMediaStore` | The storage interface: `PutAsync(key, stream, contentType)`, `OpenReadAsync(key)`, `DeleteAsync(key)`, `DeletePrefixAsync(prefix)`, `ExistsAsync`. Keys are relative paths made by the code, never by a client file name. Behind this interface the store can move from a directory to the database if the hosting demands it (risk R1). |
|
|
| `FileSystemMediaStore` | Implementation on a directory (`Media:Directory`) outside the release; atomic writes (temp file then move), path containment check (no `..`, no absolute paths, only a safe character set), no directory listing. |
|
|
| `IImageProcessor` | The image library behind an interface: `InspectAsync(stream)` (real format, size, frame count, or a rejection), `RenderAsync(source, RenderRequest)` (decode, apply orientation, crop around focus/zoom to a ratio, resize without upscaling, strip metadata, encode to a format and quality). Implementation chosen in NFR Requirements after a proof on win-x64 and linux-arm64 (candidates ImageSharp, NetVips, Magick.NET, SkiaSharp). |
|
|
| `ImageProcessingLimits` / `MediaOptions` | `Media:Directory`, maximum upload bytes (10 MB), maximum pixels, maximum parallel jobs, timeout, accepted input formats, output formats and quality per format. |
|
|
| `FocusMath`, `VariantPlanner` | Pure, property-tested: the crop rectangle for a ratio from focus and zoom (always inside the image, as close to the focus as the image allows), and the widths per ratio from the source size (no upscaling, monotonic steps). |
|
|
| `MediaPaths` | The address scheme `/media/<area>/<setHash>/<name>`; builds and parses addresses, computes the set hash from the content hash and the crop parameters, so a change of focus gives a new address. |
|
|
| `MediaEndpoint` | `GET /media/{**path}`: anonymous, same origin; `Cache-Control: public, max-age=31536000, immutable`, `ETag`, `304`, `X-Content-Type-Options: nosniff`, content type from the stored file, `Content-Disposition` not set, rate-limit policy `media-public`; unknown or malformed path = 404 with no detail. Also `HEAD`. |
|
|
| `IMediaUploadGuard` | The upload checks in one place (size, real format, pixel and memory bounds, decode timeout, parallelism gate), used by every module that accepts images. |
|
|
|
|
## C3. `SlpModularCms.Core.Hosting.Website` (Changed)
|
|
|
|
| Component | Change |
|
|
|---|---|
|
|
| `ICmsDataBlockContributor` (New) | `Key`, `Order`, `GetAsync(context, ct)` returning the value (object) for that key or "no value". |
|
|
| `CmsDataBlockTransform` (New, `IHtmlPageTransform`) | Owns the `<!--CMS:DATA-->` marker: asks all contributors (ordered by `Order`) and writes `{"siteUrl": …, <key>: <value>, …}` into the data block. Wants = page contains the marker. Fail-open as every transform. If a contributor throws, the whole block is left as baked: a half-filled block would mislead the site (fail-open for the block as a whole). |
|
|
| `OfferingsHtmlTransform` (Changed, module Offerings) | No longer writes the data block; its regions, JSON-LD and prices stay. A new `OfferingsDataContributor` (`Order` 100) supplies `offerings` and `banners`. The output of the block stays byte-identical (key order `siteUrl`, `offerings`, `banners`, then `hero`), so all existing golden files stay green. |
|
|
| `HtmlMarkerEditor` | Unchanged API; the preload marker is written through the existing `IIndexHtmlMarkerProvider` (whole-comment replacement). |
|
|
|
|
## C4. Frontend admin (New feature folder `frontend/src/features/hero`)
|
|
|
|
| Component | Purpose |
|
|
|---|---|
|
|
| `HeroPage` | The Hero screen in the admin navigation (visible when the Hero module is on, via `/System/capabilities`), shows whether the hero is live (schedule, active slides). |
|
|
| `HeroForm` | Title (multi-line), tagline, lead, display, up to two buttons with target validation messages, schedule. |
|
|
| `SlideList` | Order (up/down), on/off, alt text or "decorative", remove, add. |
|
|
| `ImageUploader` | Upload with progress, shows the accepted formats and the size limit, rejection messages. |
|
|
| `FocusEditor` | Own light component: the image with a draggable focus point, a zoom control, live previews of `wide` (3:2) and `tall` (4:5) cut as the host will cut them (same pure maths, shared as a small TypeScript twin of `FocusMath` with the same test vectors), and optional per-ratio overrides with "use the general point" reset. |
|
|
| `heroApi`, translations | React Query hooks and `nl/en` texts. |
|
|
|
|
## C5. Scripts, docs, CI
|
|
|
|
| Component | Purpose |
|
|
|---|---|
|
|
| `scripts/Seed-Hero.ps1` (+ data) | Seeds the SLP hero and the ASF hero with its 8 photos and the focus estimates of the ASF session, on test only; needs the owner's login like `Seed-Offerings.ps1`. |
|
|
| `scripts/smoke-site.sh` (Changed) | Checks the public hero endpoint (200 or 204), a media address answers with the immutable header, and, for a site with markers, no unprocessed hero markers. |
|
|
| `docs/hero-module.md` (New) | Contract, addresses, storage and the hosting risk, operation. |
|
|
| CI H0 | Done (merged, 0824bfa). |
|
|
|
|
## Sites (outside this repository)
|
|
|
|
The SLP and ASF websites place the markers and render `<picture>`; contract in `site-contract-agreed-with-asf.md`.
|