Files

5.8 KiB

Component methods: hero-module

Signatures and purposes only; business rules are detailed in Functional Design per unit. Types are C# sketches.

Core.Media

public interface IMediaStore
{
    Task PutAsync(string key, Stream content, string contentType, CancellationToken ct);
    Task<MediaFile?> OpenReadAsync(string key, CancellationToken ct);   // null = not found; MediaFile has Stream, ContentType, Length, LastWriteTime
    Task<bool> ExistsAsync(string key, CancellationToken ct);
    Task DeleteAsync(string key, CancellationToken ct);
    Task DeletePrefixAsync(string prefix, CancellationToken ct);       // removes every file below an area/hash directory
}

public interface IImageProcessor
{
    // Real format, pixel size and frame count; throws ImageRejectedException (reason code) for anything unsafe or unsupported.
    Task<ImageInfo> InspectAsync(Stream source, CancellationToken ct);

    // Decode (orientation applied), crop around the focus for a ratio, resize without upscaling, strip metadata, encode.
    Task<RenderedImage> RenderAsync(Stream source, RenderRequest request, CancellationToken ct);

    IReadOnlySet<ImageFormat> SupportedInput { get; }
    IReadOnlySet<ImageFormat> SupportedOutput { get; }                 // WebP always; AVIF when the platform can
}

public sealed record RenderRequest(Ratio Ratio, int Width, ImageFormat Format, int Quality, FocusSetting Focus);
public sealed record FocusSetting(double X, double Y, double Zoom);    // 0..1, 0..1, >= 1; default (0.5, 0.5, 1)
public sealed record Ratio(string Name, int Numerator, int Denominator); // wide 3:2, tall 4:5

public interface IMediaUploadGuard
{
    // Size, real format, pixel/memory bounds, timeout and parallel gate; returns ImageInfo or throws ImageRejectedException.
    Task<GuardedUpload> AdmitAsync(Stream upload, long declaredLength, CancellationToken ct);
}

public static class FocusMath            // pure, property-tested
{
    public static CropRect CropFor(int imageWidth, int imageHeight, Ratio ratio, FocusSetting focus);
    public static FocusSetting Normalize(FocusSetting focus);          // clamps to valid ranges
}

public static class VariantPlanner       // pure, property-tested
{
    public static IReadOnlyList<VariantSpec> Plan(int sourceWidth, int sourceHeight, IReadOnlyList<RatioPlan> ratios, IReadOnlySet<ImageFormat> outputs);
}

public static class MediaPaths           // pure
{
    public static string SetHash(string originalSha256, IEnumerable<(string Ratio, FocusSetting Focus)> crops);
    public static string Url(string area, string setHash, string name);   // "/media/hero/<setHash>/wide-1600.webp"
    public static bool TryParse(string path, out MediaAddress address);   // strict allow-list of characters
}

MediaEndpoint is a minimal-API/endpoint mapping GET|HEAD /media/{**path}: parse, open from the store, answer with the immutable headers and 304 on a matching If-None-Match; any failure is a plain 404.

Core.Hosting.Website

public interface ICmsDataBlockContributor
{
    string Key { get; }                    // "offerings", "banners", "hero"
    int Order { get; }                     // 100 Offerings, 200 Hero: fixes the key order in the block
    Task<object?> GetAsync(HtmlTransformContext context, CancellationToken ct);   // null is written as JSON null
}

public sealed class CmsDataBlockTransform(IEnumerable<ICmsDataBlockContributor> contributors) : IHtmlPageTransform
{
    public bool Wants(string html);        // page contains <!--CMS:DATA-->
    public Task<string> ApplyAsync(string html, HtmlTransformContext context, CancellationToken ct);
}

Modules.Hero

public interface IHeroService
{
    Task<HeroAdminDto?> GetAsync(string language, CancellationToken ct);              // management read incl. inactive
    Task<HeroAdminDto> SaveAsync(HeroSaveRequest request, string actor, CancellationToken ct);
}

public interface IHeroImageService
{
    Task<HeroImageDto> UploadAsync(Stream upload, long length, string actor, CancellationToken ct);
    Task<HeroImageDto> SetFocusAsync(Guid imageId, HeroFocusRequest request, string actor, CancellationToken ct); // general + optional per ratio
    Task DeleteAsync(Guid imageId, string actor, CancellationToken ct);              // refuses while a slide uses it, or detaches (decided in Functional Design)
    Task RemoveOrphansAsync(CancellationToken ct);
}

public interface IPublicHeroService
{
    Task<PublicHeroDto?> GetActiveAsync(string language, DateTimeOffset now, CancellationToken ct);   // null = 204
}

public static class ButtonTargetValidator
{
    public static ButtonTargetResult Validate(string? target);   // Anchor | Path | Https | Invalid(reason)
}

public static class HeroPictureRenderer
{
    public static string RegionHtml(PublicHeroDto hero, ITextCatalog texts);   // title, tagline, buttons, first slide <picture>
    public static string PreloadHtml(PublicHeroDto hero);                       // one or two <link rel="preload" as="image"> elements
}

DTO shape (public, GET /api/v1/hero and hero in #cms-data):

{ "display": "slideshow", "title": "…", "tagline": "…", "lead": null,
  "buttons": [ { "label": "…", "target": "/over-mij" } ],
  "slides": [ { "id": "guid", "alt": "…", "decorative": false,
     "image": { "width": 1600, "height": 1067, "focus": { "x": 0.5, "y": 0.5, "zoom": 1 },
        "src": "/media/hero/<set>/wide-1600.webp",
        "variants": [ { "ratio": "wide", "width": 1600, "type": "image/webp", "url": "…" },
                      { "ratio": "tall", "width": 960, "type": "image/webp", "url": "…" } ] } } ] }

Frontend

heroApi.getHero(), saveHero(), uploadImage(file, onProgress), setFocus(imageId, …), deleteImage(imageId); focusMath.cropFor(...) (TypeScript twin of FocusMath, same test vectors).