@simple-photo-gallery/common 1.0.5 → 2.1.0

package/dist/styles/photoswipe/photoswipe.css

@@ -0,0 +1,138 @@
+/* PhotoSwipe CSS Custom Properties - Override these in your theme */
+:root {
+  /* Background */
+  --pswp-bg-color: rgba(0, 0, 0, 1);
+
+  /* Buttons */
+  --pswp-button-color: white;
+  --pswp-button-opacity: 0.8;
+  --pswp-button-opacity-hover: 1;
+
+  /* Counter */
+  --pswp-counter-color: white;
+  --pswp-counter-font-size: 1rem;
+
+  /* Caption container */
+  --pswp-caption-bg: rgba(128, 128, 128, 0.3);
+  --pswp-caption-blur: 8px;
+  --pswp-caption-color: white;
+  --pswp-caption-padding: 16px;
+  --pswp-caption-padding-mobile: 8px 16px;
+  --pswp-caption-radius: 16px;
+  --pswp-caption-margin: 1rem;
+  --pswp-caption-margin-mobile: 8px 0;
+  --pswp-caption-shadow: 0 8px 32px rgba(0, 0, 0, 0.3);
+  --pswp-caption-max-width: 42rem;
+
+  /* Caption typography */
+  --pswp-caption-title-size: 1.5rem;
+  --pswp-caption-title-weight: 600;
+  --pswp-caption-text-size: 1rem;
+  --pswp-caption-text-size-mobile: 0.8rem;
+  --pswp-caption-description-size: 0.95rem;
+
+  /* Animation */
+  --pswp-slide-animation-duration: 0.6s;
+  --pswp-slide-animation-easing: ease-out;
+}
+
+/* PhotoSwipe enhanced styles */
+.pswp .pswp__bg {
+  --pswp-bg: var(--pswp-bg-color);
+}
+
+.pswp__counter {
+  color: var(--pswp-counter-color);
+  font-size: var(--pswp-counter-font-size);
+}
+
+.pswp__button {
+  color: var(--pswp-button-color);
+  opacity: var(--pswp-button-opacity);
+  transition: opacity 0.3s ease;
+}
+
+.pswp__button:hover {
+  opacity: var(--pswp-button-opacity-hover);
+}
+
+.pswp__caption {
+  position: absolute;
+  bottom: 0;
+  left: 50%;
+  transform: translateX(-50%);
+}
+
+@media (max-width: 768px) {
+  .pswp__caption {
+    width: calc(100% - 16px);
+  }
+}
+
+.pswp__caption .image-caption {
+  text-align: left;
+  background: var(--pswp-caption-bg);
+  backdrop-filter: blur(var(--pswp-caption-blur));
+  -webkit-backdrop-filter: blur(var(--pswp-caption-blur));
+  color: var(--pswp-caption-color);
+  padding: var(--pswp-caption-padding);
+  border-radius: var(--pswp-caption-radius);
+  margin: var(--pswp-caption-margin);
+  box-shadow: var(--pswp-caption-shadow);
+}
+
+@media (max-width: 768px) {
+  .pswp__caption .image-caption {
+    padding: var(--pswp-caption-padding-mobile);
+    font-size: var(--pswp-caption-text-size-mobile);
+    margin: var(--pswp-caption-margin-mobile);
+  }
+}
+
+.pswp__caption__center {
+  text-align: center;
+  max-width: var(--pswp-caption-max-width);
+  margin: 0 auto;
+}
+
+.pswp__caption h3 {
+  font-size: var(--pswp-caption-title-size);
+  font-weight: var(--pswp-caption-title-weight);
+  margin-bottom: 0.5rem;
+  text-shadow: 0 2px 4px rgba(0, 0, 0, 0.3);
+}
+
+.pswp__caption p {
+  font-size: var(--pswp-caption-text-size);
+  opacity: 0.95;
+  line-height: 1.6;
+  text-shadow: 0 1px 2px rgba(0, 0, 0, 0.3);
+  font-weight: 400;
+}
+
+.pswp__caption .description {
+  display: block;
+  margin-top: 0.5rem;
+  font-size: var(--pswp-caption-description-size);
+  opacity: 0.9;
+  font-weight: 300;
+  font-style: italic;
+}
+
+/* Slide-in animation */
+.pswp__img {
+  opacity: 0;
+}
+
+.pswp__img--in-viewport {
+  animation: pswp-slideIn var(--pswp-slide-animation-duration) var(--pswp-slide-animation-easing) forwards;
+}
+
+@keyframes pswp-slideIn {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}

package/dist/theme.d.ts

@@ -0,0 +1,442 @@
+import { z } from 'zod';
+
+/** Zod schema for header image variants allowing explicit specification of responsive hero images */
+declare const HeaderImageVariantsSchema: z.ZodObject<{
+    portrait: z.ZodOptional<z.ZodObject<{
+        avif: z.ZodOptional<z.ZodObject<{
+            360: z.ZodOptional<z.ZodString>;
+            480: z.ZodOptional<z.ZodString>;
+            720: z.ZodOptional<z.ZodString>;
+            1080: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        jpg: z.ZodOptional<z.ZodObject<{
+            360: z.ZodOptional<z.ZodString>;
+            480: z.ZodOptional<z.ZodString>;
+            720: z.ZodOptional<z.ZodString>;
+            1080: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    landscape: z.ZodOptional<z.ZodObject<{
+        avif: z.ZodOptional<z.ZodObject<{
+            640: z.ZodOptional<z.ZodString>;
+            960: z.ZodOptional<z.ZodString>;
+            1280: z.ZodOptional<z.ZodString>;
+            1920: z.ZodOptional<z.ZodString>;
+            2560: z.ZodOptional<z.ZodString>;
+            3840: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        jpg: z.ZodOptional<z.ZodObject<{
+            640: z.ZodOptional<z.ZodString>;
+            960: z.ZodOptional<z.ZodString>;
+            1280: z.ZodOptional<z.ZodString>;
+            1920: z.ZodOptional<z.ZodString>;
+            2560: z.ZodOptional<z.ZodString>;
+            3840: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Zod schema for complete gallery data including metadata, sections, and sub-galleries */
+declare const GalleryMetadataSchema: z.ZodObject<{
+    image: z.ZodOptional<z.ZodString>;
+    imageWidth: z.ZodOptional<z.ZodNumber>;
+    imageHeight: z.ZodOptional<z.ZodNumber>;
+    ogUrl: z.ZodOptional<z.ZodString>;
+    ogType: z.ZodOptional<z.ZodString>;
+    ogSiteName: z.ZodOptional<z.ZodString>;
+    twitterSite: z.ZodOptional<z.ZodString>;
+    twitterCreator: z.ZodOptional<z.ZodString>;
+    author: z.ZodOptional<z.ZodString>;
+    keywords: z.ZodOptional<z.ZodString>;
+    canonicalUrl: z.ZodOptional<z.ZodString>;
+    language: z.ZodOptional<z.ZodString>;
+    robots: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Zod schema for complete gallery data including metadata, sections, and sub-galleries */
+declare const GalleryDataSchema: z.ZodObject<{
+    title: z.ZodString;
+    description: z.ZodString;
+    mediaBasePath: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    headerImage: z.ZodString;
+    headerImageBlurHash: z.ZodOptional<z.ZodString>;
+    headerImageVariants: z.ZodOptional<z.ZodObject<{
+        portrait: z.ZodOptional<z.ZodObject<{
+            avif: z.ZodOptional<z.ZodObject<{
+                360: z.ZodOptional<z.ZodString>;
+                480: z.ZodOptional<z.ZodString>;
+                720: z.ZodOptional<z.ZodString>;
+                1080: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            jpg: z.ZodOptional<z.ZodObject<{
+                360: z.ZodOptional<z.ZodString>;
+                480: z.ZodOptional<z.ZodString>;
+                720: z.ZodOptional<z.ZodString>;
+                1080: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        landscape: z.ZodOptional<z.ZodObject<{
+            avif: z.ZodOptional<z.ZodObject<{
+                640: z.ZodOptional<z.ZodString>;
+                960: z.ZodOptional<z.ZodString>;
+                1280: z.ZodOptional<z.ZodString>;
+                1920: z.ZodOptional<z.ZodString>;
+                2560: z.ZodOptional<z.ZodString>;
+                3840: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            jpg: z.ZodOptional<z.ZodObject<{
+                640: z.ZodOptional<z.ZodString>;
+                960: z.ZodOptional<z.ZodString>;
+                1280: z.ZodOptional<z.ZodString>;
+                1920: z.ZodOptional<z.ZodString>;
+                2560: z.ZodOptional<z.ZodString>;
+                3840: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    theme: z.ZodOptional<z.ZodString>;
+    thumbnails: z.ZodOptional<z.ZodObject<{
+        size: z.ZodOptional<z.ZodNumber>;
+        edge: z.ZodOptional<z.ZodEnum<{
+            width: "width";
+            height: "height";
+            auto: "auto";
+        }>>;
+    }, z.core.$strip>>;
+    metadata: z.ZodObject<{
+        image: z.ZodOptional<z.ZodString>;
+        imageWidth: z.ZodOptional<z.ZodNumber>;
+        imageHeight: z.ZodOptional<z.ZodNumber>;
+        ogUrl: z.ZodOptional<z.ZodString>;
+        ogType: z.ZodOptional<z.ZodString>;
+        ogSiteName: z.ZodOptional<z.ZodString>;
+        twitterSite: z.ZodOptional<z.ZodString>;
+        twitterCreator: z.ZodOptional<z.ZodString>;
+        author: z.ZodOptional<z.ZodString>;
+        keywords: z.ZodOptional<z.ZodString>;
+        canonicalUrl: z.ZodOptional<z.ZodString>;
+        language: z.ZodOptional<z.ZodString>;
+        robots: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    mediaBaseUrl: z.ZodOptional<z.ZodString>;
+    thumbsBaseUrl: z.ZodOptional<z.ZodString>;
+    analyticsScript: z.ZodOptional<z.ZodString>;
+    ctaBanner: z.ZodOptional<z.ZodBoolean>;
+    sections: z.ZodArray<z.ZodObject<{
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        images: z.ZodArray<z.ZodObject<{
+            type: z.ZodEnum<{
+                image: "image";
+                video: "video";
+            }>;
+            filename: z.ZodString;
+            url: z.ZodOptional<z.ZodString>;
+            alt: z.ZodOptional<z.ZodString>;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            thumbnail: z.ZodOptional<z.ZodObject<{
+                baseUrl: z.ZodOptional<z.ZodString>;
+                path: z.ZodString;
+                pathRetina: z.ZodString;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+                blurHash: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            lastMediaTimestamp: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    subGalleries: z.ZodObject<{
+        title: z.ZodString;
+        galleries: z.ZodArray<z.ZodObject<{
+            title: z.ZodString;
+            headerImage: z.ZodString;
+            path: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+
+/** TypeScript type for header image variants */
+type HeaderImageVariants = z.infer<typeof HeaderImageVariantsSchema>;
+/** TypeScript type for gallery metadata */
+type GalleryMetadata = z.infer<typeof GalleryMetadataSchema>;
+/** TypeScript type for complete gallery data structure */
+type GalleryData = z.infer<typeof GalleryDataSchema>;
+
+/** Zod schema for thumbnail configuration */
+declare const ThumbnailConfigSchema: z.ZodObject<{
+    size: z.ZodOptional<z.ZodNumber>;
+    edge: z.ZodOptional<z.ZodEnum<{
+        width: "width";
+        height: "height";
+        auto: "auto";
+    }>>;
+}, z.core.$strip>;
+/** Zod schema for theme configuration file (themeConfig.json) */
+declare const ThemeConfigSchema: z.ZodObject<{
+    thumbnails: z.ZodOptional<z.ZodObject<{
+        size: z.ZodOptional<z.ZodNumber>;
+        edge: z.ZodOptional<z.ZodEnum<{
+            width: "width";
+            height: "height";
+            auto: "auto";
+        }>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** TypeScript type for thumbnail configuration */
+type ThumbnailConfig = z.infer<typeof ThumbnailConfigSchema>;
+/** TypeScript type for theme configuration */
+type ThemeConfig = z.infer<typeof ThemeConfigSchema>;
+/** Default thumbnail configuration values */
+declare const DEFAULT_THUMBNAIL_CONFIG: Required<ThumbnailConfig>;
+/**
+ * Extracts thumbnail config from gallery data.
+ * @param gallery - The gallery data object
+ * @returns ThumbnailConfig with values from gallery data
+ */
+declare function extractThumbnailConfigFromGallery(gallery: {
+    thumbnails?: ThumbnailConfig;
+}): ThumbnailConfig;
+/**
+ * Merges thumbnail configurations with hierarchy:
+ * 1. CLI flags (highest precedence)
+ * 2. gallery.json settings
+ * 3. themeConfig.json (theme defaults)
+ * 4. Built-in defaults (lowest)
+ *
+ * @param cliConfig - Config from CLI flags (optional)
+ * @param galleryConfig - Config from gallery.json (optional)
+ * @param themeConfig - Config from themeConfig.json (optional)
+ * @returns Merged thumbnail configuration with all values resolved
+ */
+declare function mergeThumbnailConfig(cliConfig?: ThumbnailConfig, galleryConfig?: ThumbnailConfig, themeConfig?: ThumbnailConfig): Required<ThumbnailConfig>;
+
+/** Resolved hero data with all paths computed and markdown parsed */
+interface ResolvedHero {
+    title: string;
+    description?: string;
+    parsedDescription: string;
+    headerImage?: string;
+    headerPhotoPath: string;
+    headerImageBlurHash?: string;
+    headerImageVariants?: HeaderImageVariants;
+    thumbnailBasePath: string;
+    imgBasename: string;
+    srcsets: {
+        portraitAvif: string;
+        portraitJpg: string;
+        landscapeAvif: string;
+        landscapeJpg: string;
+    };
+}
+/** Resolved image with all paths computed */
+interface ResolvedImage {
+    type: 'image' | 'video';
+    filename: string;
+    alt?: string;
+    width: number;
+    height: number;
+    imagePath: string;
+    thumbnailPath: string;
+    thumbnailSrcSet?: string;
+    thumbnailWidth?: number;
+    thumbnailHeight?: number;
+    blurHash?: string;
+}
+/** Resolved section with parsed markdown and resolved image paths */
+interface ResolvedSection {
+    title?: string;
+    description?: string;
+    parsedDescription: string;
+    images: ResolvedImage[];
+}
+/** Resolved sub-gallery with computed thumbnail path */
+interface ResolvedSubGallery {
+    title: string;
+    headerImage: string;
+    path: string;
+    thumbnailPath: string;
+    /** Pre-computed relative path for linking (only present when galleryJsonPath is provided to resolveGalleryData) */
+    resolvedPath?: string;
+}
+/** Fully resolved gallery data ready for rendering */
+interface ResolvedGalleryData {
+    title: string;
+    url?: string;
+    metadata: GalleryMetadata;
+    analyticsScript?: string;
+    ctaBanner?: boolean;
+    hero: ResolvedHero;
+    sections: ResolvedSection[];
+    subGalleries?: {
+        title: string;
+        galleries: ResolvedSubGallery[];
+    };
+    mediaBaseUrl?: string;
+    thumbsBaseUrl?: string;
+    /**
+     * Thumbnail configuration with dimension and edge settings.
+     * Themes should use this for display sizing (e.g., row-height for modern theme).
+     */
+    thumbnails?: Required<ThumbnailConfig>;
+}
+
+/** Portrait image sizes for responsive hero images */
+declare const PORTRAIT_SIZES: readonly [360, 480, 720, 1080];
+/** Landscape image sizes for responsive hero images */
+declare const LANDSCAPE_SIZES: readonly [640, 960, 1280, 1920, 2560, 3840];
+
+/**
+ * Renders markdown with limited formatting options.
+ * Supported: paragraphs, bold, italic, lists, code blocks, blockquotes, links
+ * Disabled: headings (rendered as paragraphs), images, HTML, tables
+ */
+declare function renderMarkdown(markdown: string): Promise<string>;
+
+/**
+ * Normalizes resource paths to be relative to the gallery root directory.
+ *
+ * @param resourcePath - The resource path (file or directory), typically relative to the gallery.json file
+ * @param galleryJsonPath - Path to the gallery.json file used to resolve relative paths
+ * @returns The normalized path relative to the gallery root directory
+ */
+declare function getRelativePath(resourcePath: string, galleryJsonPath: string): string;
+/**
+ * Get the path to a thumbnail that is relative to the gallery root directory or the thumbnails base URL.
+ *
+ * @param resourcePath - The resource path (file or directory), typically relative to the gallery.json file
+ * @param thumbsBaseUrl - The base URL for the thumbnails (gallery-level)
+ * @param thumbnailBaseUrl - Optional thumbnail-specific base URL that overrides thumbsBaseUrl if provided
+ * @returns The normalized path relative to the gallery root directory or the thumbnails base URL
+ */
+declare function getThumbnailPath(resourcePath: string, thumbsBaseUrl?: string, thumbnailBaseUrl?: string): string;
+/**
+ * Get the path to a photo that is always in the gallery root directory.
+ *
+ * @param filename - The filename to get the path for
+ * @param mediaBaseUrl - The base URL for the media
+ * @param url - Optional URL that, if provided, will be used directly regardless of base URL or path
+ * @returns The normalized path relative to the gallery root directory, or the provided URL
+ */
+declare function getPhotoPath(filename: string, mediaBaseUrl?: string, url?: string): string;
+/**
+ * Get the path to a subgallery thumbnail that is always in the subgallery directory.
+ *
+ * @param subgalleryHeaderImagePath - The path to the subgallery header image on the hard disk
+ * @returns The normalized path relative to the subgallery directory
+ */
+declare function getSubgalleryThumbnailPath(subgalleryHeaderImagePath: string): string;
+/**
+ * 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
+ */
+declare function buildHeroSrcset(variants: Record<number, string | undefined> | undefined, sizes: readonly number[], thumbnailBasePath: string, imgBasename: string, orientation: 'portrait' | 'landscape', format: 'avif' | 'jpg', useDefaultPaths: boolean): string;
+
+interface LoadGalleryDataOptions {
+    /**
+     * When true, validates the loaded JSON against the GalleryData schema.
+     * Throws a descriptive error if validation fails.
+     * @default false
+     */
+    validate?: boolean;
+}
+/**
+ * Load theme configuration from themeConfig.json file.
+ *
+ * Searches for themeConfig.json in the following locations (in priority order):
+ * 1. Current working directory (process.cwd()) - checked first
+ * 2. Provided themePath parameter - checked second
+ *
+ * The first valid configuration found is returned. This means a themeConfig.json
+ * in the project root will take precedence over the theme's built-in configuration,
+ * allowing users to override theme defaults without modifying the theme itself.
+ *
+ * **Note for theme authors:** Your theme's themeConfig.json provides sensible defaults,
+ * but users can override these by placing their own themeConfig.json in their project root.
+ *
+ * @param themePath - Optional path to the theme directory
+ * @returns The thumbnail configuration from the theme, or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * // Load from theme directory
+ * const themeConfig = loadThemeConfig('/path/to/theme');
+ *
+ * // Load from current directory
+ * const themeConfig = loadThemeConfig();
+ * ```
+ */
+declare function loadThemeConfig(themePath?: string): ThumbnailConfig | undefined;
+/**
+ * Load gallery data from a JSON file.
+ *
+ * @param galleryJsonPath - Path to the gallery.json file. Defaults to './gallery.json'.
+ * @param options - Optional settings for loading behavior.
+ * @returns The parsed gallery data
+ * @throws Error if file cannot be read, parsed, or fails validation
+ *
+ * @example
+ * ```typescript
+ * // Basic usage (no validation)
+ * const gallery = loadGalleryData('./gallery.json');
+ *
+ * // With schema validation
+ * const gallery = loadGalleryData('./gallery.json', { validate: true });
+ * ```
+ */
+declare function loadGalleryData(galleryJsonPath?: string, options?: LoadGalleryDataOptions): GalleryData;
+
+/**
+ * Options for resolving gallery data.
+ */
+interface ResolveGalleryDataOptions {
+    /**
+     * Path to the gallery.json file. When provided, enables resolution of
+     * relative paths for sub-galleries (resolvedPath field).
+     */
+    galleryJsonPath?: string;
+    /**
+     * Theme-specific thumbnail configuration from themeConfig.json.
+     * Used as fallback when gallery.json doesn't specify thumbnail settings.
+     */
+    themeConfig?: ThumbnailConfig;
+    /**
+     * CLI-specified thumbnail configuration (highest priority).
+     * Overrides both gallery.json and theme config settings.
+     */
+    cliConfig?: ThumbnailConfig;
+}
+/**
+ * Transform raw gallery data into a fully resolved structure with all paths
+ * computed and markdown parsed. This is the main API for themes.
+ *
+ * @param gallery - Raw gallery data from loadGalleryData()
+ * @param options - Optional configuration for path resolution
+ * @returns Fully resolved gallery data ready for rendering
+ */
+declare function resolveGalleryData(gallery: GalleryData, options?: ResolveGalleryDataOptions): Promise<ResolvedGalleryData>;
+
+/** Astro integration type (simplified to avoid astro dependency in common) */
+interface AstroIntegration {
+    name: string;
+    hooks: {
+        'astro:build:done': (options: {
+            dir: URL;
+        }) => void;
+    };
+}
+/**
+ * Astro integration to prevent empty content collection files from being generated.
+ * Removes empty content-assets.mjs and content-modules.mjs files after build.
+ */
+declare function preventEmptyContentFiles(): AstroIntegration;
+
+export { DEFAULT_THUMBNAIL_CONFIG, LANDSCAPE_SIZES, type LoadGalleryDataOptions, PORTRAIT_SIZES, type ResolveGalleryDataOptions, type ResolvedGalleryData, type ResolvedHero, type ResolvedImage, type ResolvedSection, type ResolvedSubGallery, type ThemeConfig, ThemeConfigSchema, type ThumbnailConfig, ThumbnailConfigSchema, buildHeroSrcset, extractThumbnailConfigFromGallery, getPhotoPath, getRelativePath, getSubgalleryThumbnailPath, getThumbnailPath, loadGalleryData, loadThemeConfig, mergeThumbnailConfig, preventEmptyContentFiles, renderMarkdown, resolveGalleryData };