diff --git a/aidlc-docs/features/media-library/assumptions-and-open-questions.md b/aidlc-docs/features/media-library/assumptions-and-open-questions.md index 586e891..d510734 100644 --- a/aidlc-docs/features/media-library/assumptions-and-open-questions.md +++ b/aidlc-docs/features/media-library/assumptions-and-open-questions.md @@ -28,3 +28,4 @@ Kept while Bryan is away (2026-11-17): no questions to him, a most probable assu | 22 | **Select all** and ranges with photos that cannot be selected (in use during a clean-up). | They are skipped by "select all" and by shift-ranges; the header box shows "some" when only part is selected. | Include them but refuse at confirmation. | `PhotoSelectionList`, `selection.ts` | | 23 | Where does Hero **list all photos** (performance)? | In memory, newest first, as the rest of the Hero repository does (a few dozen photos; the MySQL provider has limits with Guid lists). Paging comes with the screen when the count grows. | Server-side paging by `CreatedAt` (needs an index). | `HeroRepository.GetAllImagesReadOnlyAsync` | | 24 | **Tile ratios of the ASF mosaic** (assumption 1). | **Answered by the ASF session (2026-11-17, from its code)**: the mosaic shows at most 4 tiles per shoot page, from 2 photos up (layouts for 2, 3, 4). The tile shape is fixed per page by the photo count and order, not chosen per photo: **large** (photo 1) 2x2, desktop about 1:1 (max about 656x632), phone 4:3; **wide** (photo 2 with 3 or 4 photos) 2x1, desktop about 2.2:1 (max about 656x300), phone 3:2; **small** (photos 3 and 4 with 4 photos) 1x1, about 1.04:1 (max about 312x300), phone 1:1. With 2 photos: two large side by side. All object-fit cover (a crop). Widths: large and wide up to about 656 px, small about 312 px; phone half width about 175-300, full width about 350-600; retina variants 480, 640, 960, 1280. **Masonry** (portfolio): natural ratio only, no crop (rounding below half a row of 1/40 of the column width); 1, 2 or 3 columns, column width up to about 427 px; thumb now 800 px wide with the height following the ratio, variants about 480 and 800; the lightbox uses a separate `full`. Used in the design as uses `mosaic-large`, `mosaic-wide`, `mosaic-small` (each with a focus point and a desktop and phone shape) and `masonry` (no crop). | Each answer only adds use definitions. A ratio per photo (not per tile shape) would need a ratio editor. | Application design section 4 | +| 25 | **Use definitions in code** (built 2026-11-17, pure data, nothing consumes them yet). | `MediaUseDefinition` (ratios with widths, or natural) and `GalleryUses` for the ASF needs: `mosaic-large` (`tilelarge` 1:1, `tilelargem` 4:3), `mosaic-wide` (`tilewide` 11:5, `tilewidem` 3:2), `mosaic-small` (`tilesmall` 26:25, `tilesmallm` 1:1), `masonry` (`natural`, no crop). Ratio names are letters only (2 to 10) to fit the address allow-list, so a phone shape is a name with an `m` suffix. Widths: large and wide 480, 640, 960, 1280 (retina set from the ASF answer); small 312, 480, 640; masonry 480 and 800. The set hash uses the shared `MediaPaths.SetHash` formula (a test shows it equals the Hero's). Hero's own `wide` (3:2) and `tall` (4:5, not the 2:3 the first design sketch said) stay as built in `VariantPlanner`. | Other widths or ratio values change only the definitions; the ASF `full` (lightbox) variant is not defined yet (it is the full-frame preview ratio). | `Core/Media/Library/MediaUseDefinition.cs` | diff --git a/src/SlpModularCms.Core.Tests/Media/MediaUseDefinitionTests.cs b/src/SlpModularCms.Core.Tests/Media/MediaUseDefinitionTests.cs new file mode 100644 index 0000000..1d3d15e --- /dev/null +++ b/src/SlpModularCms.Core.Tests/Media/MediaUseDefinitionTests.cs @@ -0,0 +1,72 @@ +using FluentAssertions; +using SlpModularCms.Core.Media; +using SlpModularCms.Core.Media.Library; +using Xunit; + +namespace SlpModularCms.Core.Tests.Media; + +public class MediaUseDefinitionTests +{ + private const string Sha = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"; + + [Fact] + public void Every_ratio_name_and_width_fits_the_media_address_scheme() + { + foreach (var use in GalleryUses.All) + { + var plans = use.PlansFor(4000, 3000); + var specs = VariantPlanner.Plan(4000, 3000, plans, new HashSet { ImageFormat.WebP }); + specs.Should().NotBeEmpty(use.Key); + foreach (var spec in specs) + { + var name = MediaPaths.FileName(spec.Ratio.Name, spec.Width, spec.Format); + MediaPaths.TryParse($"{use.Module}/{use.SetHash(Sha)}/{name}", out _).Should().BeTrue($"{use.Key}: {name}"); + } + } + } + + [Fact] + public void The_keys_are_unique() => GalleryUses.All.Select(u => u.Key).Should().OnlyHaveUniqueItems(); + + [Fact] + public void A_mosaic_use_has_a_desktop_and_a_phone_shape_and_a_masonry_use_has_none_of_its_own() + { + GalleryUses.MosaicLarge.Ratios.Select(r => r.Name).Should().Equal("tilelarge", "tilelargem"); + GalleryUses.Masonry.Natural.Should().BeTrue(); + GalleryUses.Masonry.PlansFor(3000, 2000).Should().ContainSingle().Which.Ratio.Should().Be(new Ratio("natural", 3000, 2000)); + } + + [Fact] + public void A_natural_use_keeps_the_photos_own_shape_without_a_crop() + { + var spec = VariantPlanner.Plan(3000, 2000, GalleryUses.Masonry.PlansFor(3000, 2000), new HashSet { ImageFormat.WebP }) + .Single(s => s.Width == 800); + + (spec.Crop.Width, spec.Crop.Height).Should().Be((3000, 2000)); + spec.Height.Should().Be(533); + } + + [Fact] + public void The_crop_of_a_use_changes_its_set_hash_but_not_the_set_hash_of_another_use() + { + var focus = new Dictionary { ["tilelarge"] = new(0.2, 0.3, 1.5) }; + + GalleryUses.MosaicLarge.SetHash(Sha, focus).Should().NotBe(GalleryUses.MosaicLarge.SetHash(Sha)); + GalleryUses.MosaicWide.SetHash(Sha, focus).Should().Be(GalleryUses.MosaicWide.SetHash(Sha)); + GalleryUses.MosaicLarge.SetHash(Sha, focus).Should().Be(GalleryUses.MosaicLarge.SetHash(Sha, focus)); + } + + [Fact] + public void A_natural_use_does_not_depend_on_a_crop() + => GalleryUses.Masonry.SetHash(Sha, new Dictionary { ["natural"] = new(0.1, 0.1, 2) }).Should().Be(GalleryUses.Masonry.SetHash(Sha)); + + [Fact] + public void The_set_hash_formula_is_the_one_the_hero_uses_today() + { + // Same inputs through the shared function the hero calls: the library does not invent a second scheme. + var hero = new MediaUseDefinition("hero", "hero", [new("wide", 3, 2, [640]), new("tall", 4, 5, [480])]); + var focus = new Dictionary { ["wide"] = new(0.3, 0.4, 1.2) }; + + hero.SetHash(Sha, focus).Should().Be(MediaPaths.SetHash(Sha, [("wide", new FocusSetting(0.3, 0.4, 1.2)), ("tall", FocusSetting.Centre)])); + } +} diff --git a/src/SlpModularCms.Core/Media/Library/MediaUseDefinition.cs b/src/SlpModularCms.Core/Media/Library/MediaUseDefinition.cs new file mode 100644 index 0000000..976a695 --- /dev/null +++ b/src/SlpModularCms.Core/Media/Library/MediaUseDefinition.cs @@ -0,0 +1,72 @@ +namespace SlpModularCms.Core.Media.Library; + +/// One ratio of a use: its name (part of the file name), its shape and the widths cut for it. +public sealed record UseRatio(string Name, int Numerator, int Denominator, IReadOnlyList Widths); + +/// +/// What a USE of a photo needs (a place on a page, not the photo itself): the ratios with their widths, or the natural +/// shape of the photo without a crop. A photo can have several uses; each use has its own crop (focus per ratio) and so +/// its own set. Pure data, no behaviour that moves anything. +/// +/// For example mosaic-large; unique. +/// The module whose pages show it (also its media area). +/// Empty for a natural-ratio use. +/// The photo is shown in its own shape: no crop, one ratio taken from the photo itself. +public sealed record MediaUseDefinition(string Key, string Module, IReadOnlyList Ratios, bool Natural = false) +{ + public const string NaturalRatioName = "natural"; + + /// The ratio plans for a photo, given the focus per ratio name (centre when none is given). + public IReadOnlyList PlansFor(int sourceWidth, int sourceHeight, IReadOnlyDictionary? focus = null) + { + if (Natural) + { + var widths = Ratios.Count > 0 ? Ratios[0].Widths : []; + return [new RatioPlan(new Ratio(NaturalRatioName, sourceWidth, sourceHeight), FocusSetting.Centre, widths)]; + } + + return Ratios + .Select(r => new RatioPlan(new Ratio(r.Name, r.Numerator, r.Denominator), focus is not null && focus.TryGetValue(r.Name, out var f) ? f : FocusSetting.Centre, r.Widths)) + .ToList(); + } + + /// + /// The set hash of this use for a photo: the existing formula over the photo's hash and the crops of this use, so a + /// photo gets the same address for the same use and crops, and another use never shares a set by accident. + /// A natural-ratio use has no crop, so its set depends on the photo alone (and the use key). + /// + public string SetHash(string originalSha256, IReadOnlyDictionary? focus = null) + { + var crops = Natural + ? [(NaturalRatioName, FocusSetting.Centre)] + : Ratios.Select(r => (r.Name, focus is not null && focus.TryGetValue(r.Name, out var f) ? f : FocusSetting.Centre)).ToList(); + return MediaPaths.SetHash(originalSha256, crops); + } +} + +/// +/// The uses of the gallery that the Andrea Slop Fotografie site needs (answer of the ASF session, 2026-11-17): the +/// mosaic tiles (a shape fixed per page by the number and order of the photos, a desktop and a phone shape each) and the +/// masonry portfolio (natural shape). Ratio names are letters only, 2 to 10 long, so they fit the address allow-list. +/// +public static class GalleryUses +{ + public const string Module = "gallery"; + + private static readonly int[] Large = [480, 640, 960, 1280]; + private static readonly int[] Small = [312, 480, 640]; + + /// Photo 1 of 2 to 4: about 1:1 on desktop (max about 656 wide), 4:3 on a phone. + public static readonly MediaUseDefinition MosaicLarge = new("mosaic-large", Module, [new("tilelarge", 1, 1, Large), new("tilelargem", 4, 3, Large)]); + + /// Photo 2 of 3 or 4: about 2.2:1 on desktop, 3:2 on a phone. + public static readonly MediaUseDefinition MosaicWide = new("mosaic-wide", Module, [new("tilewide", 11, 5, Large), new("tilewidem", 3, 2, Large)]); + + /// Photos 3 and 4 of 4: about 1.04:1 on desktop (max about 312 wide), 1:1 on a phone. + public static readonly MediaUseDefinition MosaicSmall = new("mosaic-small", Module, [new("tilesmall", 26, 25, Small), new("tilesmallm", 1, 1, Small)]); + + /// The portfolio: the photo's own shape, no crop; thumbnail widths about 480 and 800. + public static readonly MediaUseDefinition Masonry = new("masonry", Module, [new(MediaUseDefinition.NaturalRatioName, 1, 1, [480, 800])], Natural: true); + + public static IReadOnlyList All { get; } = [MosaicLarge, MosaicWide, MosaicSmall, Masonry]; +}