9.0 KiB
9.0 KiB
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 the two regions <!--CMS:HERO-HTML-->…<!--/CMS:HERO-HTML--> (title, tagline, buttons and the first active slide as <picture>) and <!--CMS:HERO-PRELOAD-->…<!--/CMS:HERO-PRELOAD--> in the head (one or two <link rel="preload" as="image">), both from the same renderer so srcset/sizes/media are byte-for-byte equal. Fail-open. (Changed after the ASF golden files: the preload is a region pair, not a single marker, so no separate marker provider is needed.) |
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.