@simple-photo-gallery/theme-modern 2.0.16 → 2.0.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simple-photo-gallery/theme-modern",
-  "version": "2.0.16",
+  "version": "2.0.18",
   "description": "Modern theme for Simple Photo Gallery",
   "license": "MIT",
   "author": "Vladimir Haltakov, Tomasz Rusin",
@@ -36,7 +36,7 @@
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.1",
     "@eslint/js": "^9.30.1",
-    "@simple-photo-gallery/common": "1.0.5",
+    "@simple-photo-gallery/common": "1.0.6",
     "@types/photoswipe": "^4.1.6",
     "@typescript-eslint/eslint-plugin": "^8.35.1",
     "@typescript-eslint/parser": "^8.35.1",

package/src/features/themes/base-theme/components/footer/Footer.astro

@@ -14,7 +14,7 @@
   .footer {
     padding: 2rem 1.5rem 1.5rem;
     text-align: center;
-    background-color: transparent;
+    background-color: var(--section-bg-color-odd, var(--section-bg-color, #ffffff));
   }
 
   .footer__text {

package/src/features/themes/base-theme/components/gallery-section/GallerySection.astro

@@ -40,7 +40,7 @@ const validImages = section.images.filter(
 <style>
   .gallery-section {
     padding: 1rem 1rem;
-    background-color: var(--section-bg-color-odd, var(--section-bg-color, transparent));
+    background-color: var(--section-bg-color-odd, var(--section-bg-color, #ffffff));
   }
 
   .gallery-section:nth-child(even) {

package/src/features/themes/base-theme/components/hero/Hero.astro

@@ -1,21 +1,25 @@
 ---
 import path from 'node:path';
 
-import { getPhotoPath } from '../../utils';
+import { buildHeroSrcset, getPhotoPath, LANDSCAPE_SIZES, PORTRAIT_SIZES } from '../../utils';
 
 import HeroScrollToGalleryBtn from '@/features/themes/base-theme/components/hero/HeroScrollToGalleryBtn.astro';
 import { renderMarkdown } from '@/lib/markdown';
 
+import type { HeaderImageVariants } from '@simple-photo-gallery/common';
+
 interface Props {
   title: string;
   description?: string;
   thumbsBaseUrl?: string;
   headerImage?: string;
   headerImageBlurHash?: string;
+  headerImageVariants?: HeaderImageVariants;
   mediaBaseUrl?: string;
 }
 
-const { title, description, thumbsBaseUrl, headerImage, headerImageBlurHash, mediaBaseUrl } = Astro.props;
+const { title, description, thumbsBaseUrl, headerImage, headerImageBlurHash, headerImageVariants, mediaBaseUrl } =
+  Astro.props;
 
 // Parse description as Markdown if it exists
 const parsedDescription: string = description ? await renderMarkdown(description) : '';
@@ -28,59 +32,47 @@ const thumbnailBasePath = thumbsBaseUrl || 'gallery/images';
 
 // Original header photo
 const headerPhotoPath = getPhotoPath(headerImage || '', mediaBaseUrl);
+
+// Determine which sources to show based on headerImageVariants
+// If headerImageVariants is not set, use all generated paths (default behavior)
+// If headerImageVariants is set, only show sources for formats that are explicitly provided
+const useDefaultPaths = !headerImageVariants;
+
+// Pre-compute all srcsets - only render sources when srcset is non-empty
+// This handles edge cases like empty format objects: { avif: {} }
+const portraitAvifSrcset = buildHeroSrcset(headerImageVariants?.portrait?.avif, PORTRAIT_SIZES, thumbnailBasePath, imgBasename, 'portrait', 'avif', useDefaultPaths);
+const portraitJpgSrcset = buildHeroSrcset(headerImageVariants?.portrait?.jpg, PORTRAIT_SIZES, thumbnailBasePath, imgBasename, 'portrait', 'jpg', useDefaultPaths);
+const landscapeAvifSrcset = buildHeroSrcset(headerImageVariants?.landscape?.avif, LANDSCAPE_SIZES, thumbnailBasePath, imgBasename, 'landscape', 'avif', useDefaultPaths);
+const landscapeJpgSrcset = buildHeroSrcset(headerImageVariants?.landscape?.jpg, LANDSCAPE_SIZES, thumbnailBasePath, imgBasename, 'landscape', 'jpg', useDefaultPaths);
 ---
 
 <section class="hero">
   <div class="hero__bg-wrapper">
     {headerImageBlurHash && <canvas data-blur-hash={headerImageBlurHash} width={32} height={32} />}
     <picture class="hero__bg" id="hero-bg-picture">
-      <!-- Portrait -->
-      <source
-        type="image/avif"
-        media="(max-aspect-ratio: 3/4)"
-        srcset={`
-          ${thumbnailBasePath}/${imgBasename}_portrait_360.avif 360w,
-          ${thumbnailBasePath}/${imgBasename}_portrait_480.avif 480w,
-          ${thumbnailBasePath}/${imgBasename}_portrait_720.avif 720w,
-          ${thumbnailBasePath}/${imgBasename}_portrait_1080.avif 1080w`}
-        sizes="(max-aspect-ratio: 3/4) 160vw, 100vw"
-      />
-      <source
-        type="image/jpeg"
-        media="(max-aspect-ratio: 3/4)"
-        srcset={`
-          ${thumbnailBasePath}/${imgBasename}_portrait_360.jpg 360w,
-          ${thumbnailBasePath}/${imgBasename}_portrait_480.jpg 480w,
-          ${thumbnailBasePath}/${imgBasename}_portrait_720.jpg 720w,
-          ${thumbnailBasePath}/${imgBasename}_portrait_1080.jpg 1080w`}
-        sizes="(max-aspect-ratio: 3/4) 160vw, 100vw"
-      />
-
-      <!-- Landscape -->
-      <source
-        type="image/avif"
-        srcset={`
-          ${thumbnailBasePath}/${imgBasename}_landscape_640.avif 640w,
-          ${thumbnailBasePath}/${imgBasename}_landscape_960.avif 960w,
-          ${thumbnailBasePath}/${imgBasename}_landscape_1280.avif 1280w,
-          ${thumbnailBasePath}/${imgBasename}_landscape_1920.avif 1920w,
-          ${thumbnailBasePath}/${imgBasename}_landscape_2560.avif 2560w,
-          ${thumbnailBasePath}/${imgBasename}_landscape_3840.avif 3840w`}
-        sizes="100vw"
-      />
-      <source
-        type="image/jpg"
-        srcset={`
-        ${thumbnailBasePath}/${imgBasename}_landscape_640.jpg 640w,
-        ${thumbnailBasePath}/${imgBasename}_landscape_960.jpg 960w,
-        ${thumbnailBasePath}/${imgBasename}_landscape_1280.jpg 1280w,
-        ${thumbnailBasePath}/${imgBasename}_landscape_1920.jpg 1920w,
-        ${thumbnailBasePath}/${imgBasename}_landscape_2560.jpg 2560w,
-        ${thumbnailBasePath}/${imgBasename}_landscape_3840.jpg 3840w`}
-        sizes="100vw"
-      />
-
-      <!-- Fallback -->
+      {/* Portrait */}
+      {portraitAvifSrcset && (
+        <source
+          type="image/avif"
+          media="(max-aspect-ratio: 3/4)"
+          srcset={portraitAvifSrcset}
+          sizes="(max-aspect-ratio: 3/4) 160vw, 100vw"
+        />
+      )}
+      {portraitJpgSrcset && (
+        <source
+          type="image/jpeg"
+          media="(max-aspect-ratio: 3/4)"
+          srcset={portraitJpgSrcset}
+          sizes="(max-aspect-ratio: 3/4) 160vw, 100vw"
+        />
+      )}
+
+      {/* Landscape */}
+      {landscapeAvifSrcset && <source type="image/avif" srcset={landscapeAvifSrcset} sizes="100vw" />}
+      {landscapeJpgSrcset && <source type="image/jpeg" srcset={landscapeJpgSrcset} sizes="100vw" />}
+
+      {/* Fallback */}
       <img src={headerPhotoPath} class="hero__bg-img" />
     </picture>
     <script is:inline>
@@ -145,13 +137,13 @@ const headerPhotoPath = getPhotoPath(headerImage || '', mediaBaseUrl);
               () => {
                 // Final fallback failed, blurhash stays visible
               },
-              { once: true }
+              { once: true },
             );
 
             // If fallback succeeds, hide blurhash
             img.addEventListener('load', hideBlurhash, { once: true });
           },
-          { once: true }
+          { once: true },
         );
       })();
     </script>
@@ -168,7 +160,7 @@ const headerPhotoPath = getPhotoPath(headerImage || '', mediaBaseUrl);
   .hero {
     position: relative;
     min-height: 450px;
-    height: 100vh;
+    height: var(--hero-height, 100vh);
     display: flex;
     align-items: center;
     justify-content: center;

package/src/features/themes/base-theme/layouts/MainHead.astro

@@ -1,5 +1,7 @@
 ---
-import type { GalleryMetadata } from '@simple-photo-gallery/common/src/gallery';
+import { buildHeroSrcset, LANDSCAPE_SIZES, PORTRAIT_SIZES } from '../utils';
+
+import type { GalleryMetadata, HeaderImageVariants } from '@simple-photo-gallery/common/src/gallery';
 
 interface Props {
   title: string;
@@ -8,15 +10,45 @@ interface Props {
   thumbsBaseUrl?: string;
   metadata?: GalleryMetadata;
   headerImageBasename?: string;
+  headerImageVariants?: HeaderImageVariants;
 }
 
-const { title, description, url, thumbsBaseUrl, metadata, headerImageBasename } = Astro.props;
+const { title, description, url, thumbsBaseUrl, metadata, headerImageBasename, headerImageVariants } = Astro.props;
 
 // Use headerImageBasename for dynamic image paths, fallback to generic name
 const imgBasename = headerImageBasename || 'header';
 
 // Get the base path for the thumbnails
 const thumbnailBasePath = thumbsBaseUrl || 'gallery/images';
+
+// Determine which sources to show based on headerImageVariants
+// If headerImageVariants is not set, use all generated paths (default behavior)
+// If headerImageVariants is set, only show sources for formats that are explicitly provided
+const useDefaultPaths = !headerImageVariants;
+
+// Pre-compute srcsets - only non-empty srcsets will be rendered
+// This handles edge cases like empty format objects: { avif: {} }
+const portraitAvifSrcset = buildHeroSrcset(headerImageVariants?.portrait?.avif, PORTRAIT_SIZES, thumbnailBasePath, imgBasename, 'portrait', 'avif', useDefaultPaths);
+const portraitJpgSrcset = buildHeroSrcset(headerImageVariants?.portrait?.jpg, PORTRAIT_SIZES, thumbnailBasePath, imgBasename, 'portrait', 'jpg', useDefaultPaths);
+const landscapeAvifSrcset = buildHeroSrcset(headerImageVariants?.landscape?.avif, LANDSCAPE_SIZES, thumbnailBasePath, imgBasename, 'landscape', 'avif', useDefaultPaths);
+const landscapeJpgSrcset = buildHeroSrcset(headerImageVariants?.landscape?.jpg, LANDSCAPE_SIZES, thumbnailBasePath, imgBasename, 'landscape', 'jpg', useDefaultPaths);
+
+// Determine media queries for preloads to match actual <source> media attributes in Hero.astro
+// Portrait <source> always has media="(max-aspect-ratio: 3/4)", so preload must use the same restriction
+// Otherwise landscape devices would preload portrait images they'll never use (wasting bandwidth)
+// Landscape sources have no media restriction in Hero.astro, but we add one here when ANY portrait source exists
+// to prevent landscape images from being preloaded on portrait devices (which will use portrait sources)
+// We check both AVIF and JPG because portrait devices will use whichever portrait format is available
+const hasAnyPortraitSource = portraitAvifSrcset || portraitJpgSrcset;
+const portraitPreloadMedia = '(max-aspect-ratio: 3/4)';
+const landscapePreloadMedia = hasAnyPortraitSource ? 'not (max-aspect-ratio: 3/4)' : undefined;
+
+// Determine which format to preload for each orientation
+// Prefer AVIF when available (better compression), fall back to JPG for JPG-only configurations
+const portraitPreloadSrcset = portraitAvifSrcset || portraitJpgSrcset;
+const portraitPreloadType = portraitAvifSrcset ? 'image/avif' : 'image/jpeg';
+const landscapePreloadSrcset = landscapeAvifSrcset || landscapeJpgSrcset;
+const landscapePreloadType = landscapeAvifSrcset ? 'image/avif' : 'image/jpeg';
 ---
 
 <head>
@@ -77,22 +109,26 @@ const thumbnailBasePath = thumbsBaseUrl || 'gallery/images';
     href="https://fonts.googleapis.com/css2?family=Montserrat:ital,wght@0,100..900;1,100..900&display=swap"
     rel="stylesheet"
   />
-  <link
-    rel="preload"
-    as="image"
-    type="image/avif"
-    media="(max-aspect-ratio: 3/4)"
-    imagesrcset={`${thumbnailBasePath}/${imgBasename}_portrait_360.avif 360w, ${thumbnailBasePath}/${imgBasename}_portrait_480.avif 480w, ${thumbnailBasePath}/${imgBasename}_portrait_720.avif 720w, ${thumbnailBasePath}/${imgBasename}_portrait_1080.avif 1080w`}
-    imagesizes="(max-aspect-ratio: 3/4) 160vw, 100vw"
-    fetchpriority="high"
-  />
-  <link
-    rel="preload"
-    as="image"
-    type="image/avif"
-    media="(min-aspect-ratio: 3/4)"
-    imagesrcset={`${thumbnailBasePath}/${imgBasename}_landscape_640.avif 640w, ${thumbnailBasePath}/${imgBasename}_landscape_960.avif 960w, ${thumbnailBasePath}/${imgBasename}_landscape_1280.avif 1280w, ${thumbnailBasePath}/${imgBasename}_landscape_1920.avif 1920w, ${thumbnailBasePath}/${imgBasename}_landscape_2560.avif 2560w, ${thumbnailBasePath}/${imgBasename}_landscape_3840.avif 3840w`}
-    imagesizes="100vw"
-    fetchpriority="high"
-  />
+  {portraitPreloadSrcset && (
+    <link
+      rel="preload"
+      as="image"
+      type={portraitPreloadType}
+      media={portraitPreloadMedia}
+      imagesrcset={portraitPreloadSrcset}
+      imagesizes="(max-aspect-ratio: 3/4) 160vw, 100vw"
+      fetchpriority="high"
+    />
+  )}
+  {landscapePreloadSrcset && (
+    <link
+      rel="preload"
+      as="image"
+      type={landscapePreloadType}
+      media={landscapePreloadMedia}
+      imagesrcset={landscapePreloadSrcset}
+      imagesizes="100vw"
+      fetchpriority="high"
+    />
+  )}
 </head>

package/src/features/themes/base-theme/layouts/MainLayout.astro

@@ -3,7 +3,7 @@ import path from 'node:path';
 
 import MainHead from '@/features/themes/base-theme/layouts/MainHead.astro';
 
-import type { GalleryMetadata } from '@simple-photo-gallery/common/src/gallery';
+import type { GalleryMetadata, HeaderImageVariants } from '@simple-photo-gallery/common/src/gallery';
 
 interface Props {
   title: string;
@@ -13,9 +13,11 @@ interface Props {
   metadata?: GalleryMetadata;
   analyticsScript?: string;
   headerImage?: string;
+  headerImageVariants?: HeaderImageVariants;
 }
 
-const { title, description, metadata, url, thumbsBaseUrl, analyticsScript, headerImage } = Astro.props;
+const { title, description, metadata, url, thumbsBaseUrl, analyticsScript, headerImage, headerImageVariants } =
+  Astro.props;
 
 // Extract basename from headerImage filename
 const headerImageBasename = headerImage ? path.basename(headerImage, path.extname(headerImage)) : undefined;
@@ -30,6 +32,7 @@ const headerImageBasename = headerImage ? path.basename(headerImage, path.extnam
     url={url}
     thumbsBaseUrl={thumbsBaseUrl}
     headerImageBasename={headerImageBasename}
+    headerImageVariants={headerImageVariants}
   />
   <body>
     <slot />

package/src/features/themes/base-theme/pages/index.astro

@@ -29,6 +29,7 @@ const {
   analyticsScript,
   headerImage,
   headerImageBlurHash,
+  headerImageVariants,
   ctaBanner,
 } = gallery;
 
@@ -66,12 +67,14 @@ const showCtaBanner = ctaBanner === true;
   url={url}
   thumbsBaseUrl={thumbsBaseUrl}
   analyticsScript={analyticsScript}
-  headerImage={headerImage}>
+  headerImage={headerImage}
+  headerImageVariants={headerImageVariants}>
   <Hero
     title={title}
     description={description}
     headerImage={headerImage}
     headerImageBlurHash={headerImageBlurHash}
+    headerImageVariants={headerImageVariants}
     thumbsBaseUrl={thumbsBaseUrl}
     mediaBaseUrl={mediaBaseUrl}
   />

package/src/features/themes/base-theme/utils/index.ts

@@ -62,3 +62,46 @@ export const getSubgalleryThumbnailPath = (subgalleryHeaderImagePath: string) =>
 
   return path.join(subgalleryFolderName, 'gallery', 'thumbnails', photoBasename);
 };
+
+/** Portrait image sizes for responsive hero images */
+export const PORTRAIT_SIZES = [360, 480, 720, 1080] as const;
+
+/** Landscape image sizes for responsive hero images */
+export const LANDSCAPE_SIZES = [640, 960, 1280, 1920, 2560, 3840] as const;
+
+/**
+ * Build a srcset string for responsive images.
+ * Uses custom paths from variants when provided, otherwise generates default paths.
+ *
+ * @param variants - Optional record mapping sizes to custom URLs
+ * @param sizes - Array of image widths to include
+ * @param thumbnailBasePath - Base path for generated thumbnails
+ * @param imgBasename - Image basename for generated paths
+ * @param orientation - 'portrait' or 'landscape'
+ * @param format - Image format ('avif' or 'jpg')
+ * @param useDefaultPaths - Whether to use generated paths when no custom variant exists
+ * @returns Comma-separated srcset string
+ */
+export const buildHeroSrcset = (
+  variants: Record<number, string | undefined> | undefined,
+  sizes: readonly number[],
+  thumbnailBasePath: string,
+  imgBasename: string,
+  orientation: 'portrait' | 'landscape',
+  format: 'avif' | 'jpg',
+  useDefaultPaths: boolean,
+): string => {
+  return sizes
+    .map((size) => {
+      const customPath = variants?.[size];
+      if (customPath) {
+        return `${customPath} ${size}w`;
+      }
+      if (useDefaultPaths) {
+        return `${thumbnailBasePath}/${imgBasename}_${orientation}_${size}.${format} ${size}w`;
+      }
+      return null;
+    })
+    .filter(Boolean)
+    .join(', ');
+};

package/src/features/themes/base-theme/utils/queryParams.ts

@@ -134,6 +134,16 @@ const applySectionBackgroundColors = (params: URLSearchParams): void => {
   setCSSVar(root, '--section-bg-color-odd', parseColor(params.get('sectionBgColorOdd')));
 };
 
+/**
+ * Applies hero height from the 'heroHeight' query parameter.
+ * Accepts a number (e.g., '100' for 100vh, '50' for 50vh).
+ */
+const applyHeroHeight = (params: URLSearchParams): void => {
+  const value = params.get('heroHeight')?.trim();
+  const height = value && /^\d+(\.\d+)?$/.test(value) ? `${value}vh` : null;
+  setCSSVar(document.documentElement, '--hero-height', height);
+};
+
 /**
  * Main function that applies all query parameter configurations to the page.
  * Reads URL search params and applies header visibility, background, typography, and section colors.
@@ -145,4 +155,5 @@ export const applyQueryParams = (): void => {
   applyTransparentBackground(params);
   applyTypographyColors(params);
   applySectionBackgroundColors(params);
+  applyHeroHeight(params);
 };