From b3280eb7bf6c7ad735fca751158a4debae54e06c Mon Sep 17 00:00:00 2001 From: rustoma Date: Tue, 23 Dec 2025 08:23:02 +0100 Subject: [PATCH 01/55] feat: add theme package option for gallery build --- gallery/src/index.ts | 1 + gallery/src/modules/build/index.ts | 13 ++++++++++--- gallery/src/modules/build/types/index.ts | 2 ++ 3 files changed, 13 insertions(+), 3 deletions(-) diff --git a/gallery/src/index.ts b/gallery/src/index.ts index cc0b174..dc3a87a 100644 --- a/gallery/src/index.ts +++ b/gallery/src/index.ts @@ -179,6 +179,7 @@ program .option('-t, --thumbs-base-url ', 'Base URL where the thumbnails are hosted') .option('--no-thumbnails', 'Skip creating thumbnails when building the gallery', true) .option('--no-scan', 'Do not scan for new photos when building the gallery', true) + .option('--theme ', 'Theme package to use (e.g., @simple-photo-gallery/theme-modern or @your-org/your-private-theme)', '@simple-photo-gallery/theme-modern') .action(withCommandContext((options, ui) => build(options, ui))); program diff --git a/gallery/src/modules/build/index.ts b/gallery/src/modules/build/index.ts index d46614a..77e1ac1 100644 --- a/gallery/src/modules/build/index.ts +++ b/gallery/src/modules/build/index.ts @@ -267,10 +267,15 @@ export async function build(options: BuildOptions, ui: ConsolaInstance): Promise return { processedGalleryCount: 0 }; } - // Get the astro theme directory from the default one - const themePath = await import.meta.resolve('@simple-photo-gallery/theme-modern/package.json'); + // Get the theme package name (default to the modern theme) + const themePackage = options.theme || '@simple-photo-gallery/theme-modern'; + + // Get the astro theme directory from the specified theme package + const themePath = await import.meta.resolve(`${themePackage}/package.json`); const themeDir = path.dirname(new URL(themePath).pathname); + ui.debug(`Using theme: ${themePackage} (${themeDir})`); + // Process each gallery directory let totalGalleries = 0; for (const dir of galleryDirs) { @@ -289,7 +294,9 @@ export async function build(options: BuildOptions, ui: ConsolaInstance): Promise return { processedGalleryCount: totalGalleries }; } catch (error) { if (error instanceof Error && error.message.includes('Cannot find package')) { - ui.error('Theme package not found: @simple-photo-gallery/theme-modern/package.json'); + ui.error( + `Theme package not found: ${options.theme || '@simple-photo-gallery/theme-modern'}. Make sure it's installed.`, + ); } else { ui.error('Error building gallery'); } diff --git a/gallery/src/modules/build/types/index.ts b/gallery/src/modules/build/types/index.ts index 97552ae..63b03bd 100644 --- a/gallery/src/modules/build/types/index.ts +++ b/gallery/src/modules/build/types/index.ts @@ -12,4 +12,6 @@ export interface BuildOptions { scan: boolean; /** Create thumbnails */ thumbnails: boolean; + /** Theme package name to use for building (e.g., '@simple-photo-gallery/theme-modern' or '@your-org/your-private-theme') */ + theme?: string; } From cf68b3f3bb6f36264a5f32dd997ca755ecf13e8c Mon Sep 17 00:00:00 2001 From: rustoma Date: Tue, 23 Dec 2025 08:26:43 +0100 Subject: [PATCH 02/55] docs: add custom themes documentation and update build command options --- docs/README.md | 1 + docs/commands/build.md | 30 +++-- docs/themes.md | 278 +++++++++++++++++++++++++++++++++++++++++ gallery/src/index.ts | 6 +- 4 files changed, 303 insertions(+), 12 deletions(-) create mode 100644 docs/themes.md diff --git a/docs/README.md b/docs/README.md index c6c9da3..ce7b731 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,6 +6,7 @@ Complete documentation for the Simple Photo Gallery CLI tool. - **[Commands](./commands/README.md)** - All CLI commands and options - **[Gallery Configuration](./configuration.md)** - Manual editing of gallery.json +- **[Custom Themes](./themes.md)** - Create and use custom themes - **[Deployment](./deployment.md)** - Hosting and deployment options - **[Embedding](./embedding.md)** - Customize the gallery when embedding in another site diff --git a/docs/commands/build.md b/docs/commands/build.md index 13cea56..1c9d570 100644 --- a/docs/commands/build.md +++ b/docs/commands/build.md @@ -14,17 +14,18 @@ If you have created the gallery in a different folder from the photos folder, th ## Options -| Option | Description | Default | -| ----------------------------- | ------------------------------------------- | ----------------- | -| `-g, --gallery ` | Path to gallery directory | Current directory | -| `-r, --recursive` | Build all galleries | `false` | -| `-b, --base-url ` | Base URL for external hosting | None | -| `-t, --thumbs-base-url ` | Base URL for external hosting of thumbnails | None | -| `--no-scan` | Do not scan for new photos | `true` | -| `--no-thumbnails` | Skip creating thumbnails | `true` | -| `-v, --verbose` | Show detailed output | | -| `-q, --quiet` | Only show warnings/errors | | -| `-h, --help` | Show command help | | +| Option | Description | Default | +| ----------------------------- | ------------------------------------------- | ------------------------------------ | +| `-g, --gallery ` | Path to gallery directory | Current directory | +| `-r, --recursive` | Build all galleries | `false` | +| `-b, --base-url ` | Base URL for external hosting | None | +| `-t, --thumbs-base-url ` | Base URL for external hosting of thumbnails | None | +| `--theme ` | Theme package to use | `@simple-photo-gallery/theme-modern` | +| `--no-scan` | Do not scan for new photos | `true` | +| `--no-thumbnails` | Skip creating thumbnails | `true` | +| `-v, --verbose` | Show detailed output | | +| `-q, --quiet` | Only show warnings/errors | | +| `-h, --help` | Show command help | | ## Examples @@ -49,4 +50,11 @@ spg build --no-scan # Build without creating thumbnails spg build --no-thumbnails + +# Build with a custom theme package +spg build --theme @your-org/your-private-theme ``` + +## Custom Themes + +You can use custom theme packages by specifying the `--theme` option. The theme package must be installed as a dependency in your project. See the [Custom Themes](../themes.md) guide for requirements and how to create your own theme. diff --git a/docs/themes.md b/docs/themes.md new file mode 100644 index 0000000..7061da9 --- /dev/null +++ b/docs/themes.md @@ -0,0 +1,278 @@ +# Custom Themes + +Simple Photo Gallery supports custom themes, allowing you to create your own visual design and layout while leveraging the gallery's core functionality. + +## Using Custom Themes + +To use a custom theme, install it as a dependency and specify it when building: + +```bash +# Install your custom theme package +npm install @your-org/your-private-theme + +# Build with the custom theme +spg build --theme @your-org/your-private-theme +``` + +If you don't specify `--theme`, the default `@simple-photo-gallery/theme-modern` theme will be used. + +## Creating a Custom Theme + +A theme is an npm package built with [Astro](https://astro.build/) that follows a specific structure and interface. + +### Package Structure + +Your theme package should have the following structure: + +``` +your-theme-package/ +├── package.json +├── astro.config.ts +├── tsconfig.json +└── src/ + └── pages/ + └── index.astro +``` + +### Required Files + +#### 1. `package.json` + +Your theme package must be a valid npm package with: + +- A unique package name (e.g., `@your-org/your-theme-name`) +- `"type": "module"` for ES modules support +- Required dependencies (see below) +- Files array that includes all necessary files: + +```json +{ + "name": "@your-org/your-theme-name", + "version": "1.0.0", + "type": "module", + "files": ["public", "src", "astro.config.ts", "tsconfig.json"], + "dependencies": { + "astro": "^5.11.0", + "@simple-photo-gallery/common": "^1.0.5" + } +} +``` + +#### 2. `astro.config.ts` + +Your Astro config must: + +- Use `output: 'static'` for static site generation +- Set `outDir` to `${outputDir}/_build` where `outputDir` comes from `process.env.GALLERY_OUTPUT_DIR` +- Define `process.env.GALLERY_JSON_PATH` in Vite's `define` config +- Use the `astro-relative-links` integration (recommended) + +Example: + +```typescript +import { defineConfig } from "astro/config"; +import relativeLinks from "astro-relative-links"; + +const sourceGalleryPath = process.env.GALLERY_JSON_PATH; +if (!sourceGalleryPath) { + throw new Error("GALLERY_JSON_PATH environment variable is not set"); +} + +const outputDir = + process.env.GALLERY_OUTPUT_DIR || + sourceGalleryPath.replace("gallery.json", ""); + +export default defineConfig({ + output: "static", + outDir: outputDir + "/_build", + build: { + assets: "assets", + assetsPrefix: "gallery", + }, + integrations: [relativeLinks()], + vite: { + define: { + "process.env.GALLERY_JSON_PATH": JSON.stringify(sourceGalleryPath), + }, + }, +}); +``` + +#### 3. `src/pages/index.astro` + +This is your main theme entry point. It must: + +- Read `gallery.json` from the path specified in `process.env.GALLERY_JSON_PATH` +- Parse and use the `GalleryData` structure +- Generate valid HTML output + +Example: + +```astro +--- +import fs from 'node:fs'; +import type { GalleryData } from '@simple-photo-gallery/common/src/gallery'; + +// Read gallery.json from the path provided by the build process +const galleryJsonPath = process.env.GALLERY_JSON_PATH || './gallery.json'; +const galleryData = JSON.parse(fs.readFileSync(galleryJsonPath, 'utf8')); +const gallery = galleryData as GalleryData; + +// Extract gallery properties +const { + title, + description, + metadata, + sections, + subGalleries, + mediaBaseUrl, + thumbsBaseUrl, + url, + analyticsScript, + headerImage, + headerImageBlurHash, + ctaBanner, +} = gallery; +--- + + + + {title} + + {analyticsScript && ( + + )} + + + +

{title}

+

{description}

+ + + {sections.map((section) => ( +
+ {section.images.map((image) => ( + {image.caption + ))} +
+ ))} + + +``` + +### Gallery Data Structure + +Your theme receives a `GalleryData` object with the following structure: + +```typescript +interface GalleryData { + title: string; + description: string; + headerImage: string; + headerImageBlurHash?: string; + mediaBasePath?: string; + mediaBaseUrl?: string; + thumbsBaseUrl?: string; + url?: string; + analyticsScript?: string; + ctaBanner?: boolean; + thumbnailSize?: number; + metadata: { + image?: string; + imageWidth?: number; + imageHeight?: number; + ogUrl?: string; + ogType?: string; + ogSiteName?: string; + twitterSite?: string; + twitterCreator?: string; + author?: string; + keywords?: string; + canonicalUrl?: string; + robots?: string; + }; + sections: Array<{ + title?: string; + description?: string; + images: Array<{ + filename: string; + width: number; + height: number; + caption?: string; + description?: string; + blurHash?: string; + thumbnail?: { + filename: string; + width: number; + height: number; + }; + // ... other image properties + }>; + }>; + subGalleries?: { + title: string; + galleries: Array<{ + title: string; + headerImage: string; + path: string; + }>; + }; +} +``` + +### Environment Variables + +The build process sets these environment variables that your theme can access: + +- `GALLERY_JSON_PATH`: Absolute path to the `gallery.json` file +- `GALLERY_OUTPUT_DIR`: Directory where the built gallery should be output + +### Build Process + +When building, the gallery CLI will: + +1. Set `GALLERY_JSON_PATH` and `GALLERY_OUTPUT_DIR` environment variables +2. Run `npx astro build` in your theme package directory +3. Copy the built output from `_build` to the gallery output directory +4. Move `index.html` to the gallery root + +Your theme must output an `index.html` file in the build directory. + +### Best Practices + +1. **Use TypeScript**: Import types from `@simple-photo-gallery/common` for type safety +2. **Handle optional fields**: Many fields in `GalleryData` are optional - always check before using +3. **Respect base URLs**: Use `mediaBaseUrl` and `thumbsBaseUrl` when provided for external hosting +4. **Optimize assets**: Use Astro's asset optimization features +5. **Test locally**: Use `astro dev` to preview your theme during development +6. **Follow Astro conventions**: Use Astro components, layouts, and best practices + +### Example Theme Package + +You can use `@simple-photo-gallery/theme-modern` as a reference implementation. The source code is available in the [themes/modern](../themes/modern) directory of this repository. + +### Publishing Your Theme + +Once your theme is ready: + +1. Publish it to npm (or your private registry) +2. Install it in your project: `npm install @your-org/your-theme-name` +3. Use it when building: `spg build --theme @your-org/your-theme-name` + +### Troubleshooting + +**Theme package not found** + +- Ensure the theme package is installed: `npm install @your-org/your-theme-name` +- Verify the package name matches exactly (including scope) + +**Build errors** + +- Check that `GALLERY_JSON_PATH` is being read correctly +- Verify your `astro.config.ts` matches the required structure +- Ensure all dependencies are installed + +**Missing gallery data** + +- Verify `gallery.json` exists at the expected path +- Check that the `GalleryData` structure matches the expected format diff --git a/gallery/src/index.ts b/gallery/src/index.ts index dc3a87a..609460a 100644 --- a/gallery/src/index.ts +++ b/gallery/src/index.ts @@ -179,7 +179,11 @@ program .option('-t, --thumbs-base-url ', 'Base URL where the thumbnails are hosted') .option('--no-thumbnails', 'Skip creating thumbnails when building the gallery', true) .option('--no-scan', 'Do not scan for new photos when building the gallery', true) - .option('--theme ', 'Theme package to use (e.g., @simple-photo-gallery/theme-modern or @your-org/your-private-theme)', '@simple-photo-gallery/theme-modern') + .option( + '--theme ', + 'Theme package to use (e.g., @simple-photo-gallery/theme-modern or @your-org/your-private-theme)', + '@simple-photo-gallery/theme-modern', + ) .action(withCommandContext((options, ui) => build(options, ui))); program From f7a5dbbd636d7811ade9503dc87d670ff3aa90c6 Mon Sep 17 00:00:00 2001 From: rustoma Date: Sun, 28 Dec 2025 11:38:11 +0100 Subject: [PATCH 03/55] docs: enhance custom themes documentation and update build command to support local theme paths --- docs/commands/build.md | 36 +++++++++++------- docs/themes.md | 41 +++++++++++++++++--- gallery/src/index.ts | 4 +- gallery/src/modules/build/index.ts | 61 +++++++++++++++++++++++------- 4 files changed, 107 insertions(+), 35 deletions(-) diff --git a/docs/commands/build.md b/docs/commands/build.md index 1c9d570..72d7416 100644 --- a/docs/commands/build.md +++ b/docs/commands/build.md @@ -14,18 +14,18 @@ If you have created the gallery in a different folder from the photos folder, th ## Options -| Option | Description | Default | -| ----------------------------- | ------------------------------------------- | ------------------------------------ | -| `-g, --gallery ` | Path to gallery directory | Current directory | -| `-r, --recursive` | Build all galleries | `false` | -| `-b, --base-url ` | Base URL for external hosting | None | -| `-t, --thumbs-base-url ` | Base URL for external hosting of thumbnails | None | -| `--theme ` | Theme package to use | `@simple-photo-gallery/theme-modern` | -| `--no-scan` | Do not scan for new photos | `true` | -| `--no-thumbnails` | Skip creating thumbnails | `true` | -| `-v, --verbose` | Show detailed output | | -| `-q, --quiet` | Only show warnings/errors | | -| `-h, --help` | Show command help | | +| Option | Description | Default | +| ----------------------------- | ------------------------------------------- | -------------------------------- | ------------------------------------ | +| `-g, --gallery ` | Path to gallery directory | Current directory | +| `-r, --recursive` | Build all galleries | `false` | +| `-b, --base-url ` | Base URL for external hosting | None | +| `-t, --thumbs-base-url ` | Base URL for external hosting of thumbnails | None | +| `--theme ` | Theme package name or local path | `@simple-photo-gallery/theme-modern` | +| `--no-scan` | Do not scan for new photos | `true` | +| `--no-thumbnails` | Skip creating thumbnails | `true` | +| `-v, --verbose` | Show detailed output | | +| `-q, --quiet` | Only show warnings/errors | | +| `-h, --help` | Show command help | | ## Examples @@ -51,10 +51,18 @@ spg build --no-scan # Build without creating thumbnails spg build --no-thumbnails -# Build with a custom theme package +# Build with a custom theme package (npm) spg build --theme @your-org/your-private-theme + +# Build with a local theme (path) +spg build --theme ./themes/my-local-theme ``` ## Custom Themes -You can use custom theme packages by specifying the `--theme` option. The theme package must be installed as a dependency in your project. See the [Custom Themes](../themes.md) guide for requirements and how to create your own theme. +You can use custom themes by specifying the `--theme` option. Themes can be: + +- **npm packages**: Install as a dependency and use the package name (e.g., `@your-org/your-private-theme`) +- **Local paths**: Use a relative or absolute path to a local theme directory (e.g., `./themes/my-local-theme`) + +See the [Custom Themes](../themes.md) guide for requirements and how to create your own theme. diff --git a/docs/themes.md b/docs/themes.md index 7061da9..3c3330f 100644 --- a/docs/themes.md +++ b/docs/themes.md @@ -4,7 +4,11 @@ Simple Photo Gallery supports custom themes, allowing you to create your own vis ## Using Custom Themes -To use a custom theme, install it as a dependency and specify it when building: +You can use custom themes in two ways: + +### Using npm Packages + +Install the theme as a dependency and use the package name: ```bash # Install your custom theme package @@ -14,6 +18,20 @@ npm install @your-org/your-private-theme spg build --theme @your-org/your-private-theme ``` +### Using Local Themes + +You can also use a local theme directory without publishing to npm: + +```bash +# Build with a local theme (relative path) +spg build --theme ./themes/my-local-theme + +# Build with a local theme (absolute path) +spg build --theme /path/to/my-theme +``` + +The local theme directory must contain a `package.json` file and follow the same structure as an npm theme package. + If you don't specify `--theme`, the default `@simple-photo-gallery/theme-modern` theme will be used. ## Creating a Custom Theme @@ -251,20 +269,31 @@ Your theme must output an `index.html` file in the build directory. You can use `@simple-photo-gallery/theme-modern` as a reference implementation. The source code is available in the [themes/modern](../themes/modern) directory of this repository. -### Publishing Your Theme +### Using Your Theme + +Once your theme is ready, you can use it in two ways: -Once your theme is ready: +**Option 1: Local Development (No Publishing Required)** +```bash +# Use the local theme directly +spg build --theme ./themes/my-theme +``` +**Option 2: Publish to npm** 1. Publish it to npm (or your private registry) 2. Install it in your project: `npm install @your-org/your-theme-name` 3. Use it when building: `spg build --theme @your-org/your-theme-name` +Local themes are perfect for development and private projects, while npm packages are ideal for sharing themes with others or using across multiple projects. + ### Troubleshooting -**Theme package not found** +**Theme not found** -- Ensure the theme package is installed: `npm install @your-org/your-theme-name` -- Verify the package name matches exactly (including scope) +- For npm packages: Ensure the theme package is installed: `npm install @your-org/your-theme-name` +- For npm packages: Verify the package name matches exactly (including scope) +- For local paths: Verify the path is correct and the directory contains a `package.json` file +- For local paths: Use an absolute path or a path relative to your current working directory **Build errors** diff --git a/gallery/src/index.ts b/gallery/src/index.ts index 609460a..e9f3aff 100644 --- a/gallery/src/index.ts +++ b/gallery/src/index.ts @@ -180,8 +180,8 @@ program .option('--no-thumbnails', 'Skip creating thumbnails when building the gallery', true) .option('--no-scan', 'Do not scan for new photos when building the gallery', true) .option( - '--theme ', - 'Theme package to use (e.g., @simple-photo-gallery/theme-modern or @your-org/your-private-theme)', + '--theme ', + 'Theme package name (e.g., @simple-photo-gallery/theme-modern) or local path (e.g., ./themes/my-theme)', '@simple-photo-gallery/theme-modern', ) .action(withCommandContext((options, ui) => build(options, ui))); diff --git a/gallery/src/modules/build/index.ts b/gallery/src/modules/build/index.ts index 77e1ac1..91219d1 100644 --- a/gallery/src/modules/build/index.ts +++ b/gallery/src/modules/build/index.ts @@ -254,10 +254,42 @@ async function buildGallery( } /** - * Main build command implementation - builds HTML galleries from gallery.json files - * @param options - Options specifying gallery path, recursion, and base URL + * Determines if a theme identifier is a local path or an npm package name + * @param theme - Theme identifier (path or package name) + * @returns true if it's a path, false if it's a package name + */ +function isLocalThemePath(theme: string): boolean { + // Check if it starts with ./ or ../ or / or contains path separators + return theme.startsWith('./') || theme.startsWith('../') || theme.startsWith('/') || theme.includes(path.sep); +} + +/** + * Resolves the theme directory from either a local path or npm package name + * @param theme - Theme identifier (path or package name) * @param ui - ConsolaInstance for logging + * @returns Promise resolving to the theme directory path */ +async function resolveThemeDir(theme: string, ui: ConsolaInstance): Promise { + if (isLocalThemePath(theme)) { + // Resolve local path + const themeDir = path.resolve(theme); + const packageJsonPath = path.join(themeDir, 'package.json'); + + if (!fs.existsSync(packageJsonPath)) { + throw new Error(`Theme directory not found or invalid: ${themeDir}. package.json not found.`); + } + + ui.debug(`Using local theme: ${themeDir}`); + return themeDir; + } else { + // Resolve npm package + const themePath = await import.meta.resolve(`${theme}/package.json`); + const themeDir = path.dirname(new URL(themePath).pathname); + ui.debug(`Using npm theme package: ${theme} (${themeDir})`); + return themeDir; + } +} + export async function build(options: BuildOptions, ui: ConsolaInstance): Promise { try { // Find all gallery directories @@ -267,14 +299,11 @@ export async function build(options: BuildOptions, ui: ConsolaInstance): Promise return { processedGalleryCount: 0 }; } - // Get the theme package name (default to the modern theme) - const themePackage = options.theme || '@simple-photo-gallery/theme-modern'; + // Get the theme identifier (default to the modern theme) + const themeIdentifier = options.theme || '@simple-photo-gallery/theme-modern'; - // Get the astro theme directory from the specified theme package - const themePath = await import.meta.resolve(`${themePackage}/package.json`); - const themeDir = path.dirname(new URL(themePath).pathname); - - ui.debug(`Using theme: ${themePackage} (${themeDir})`); + // Resolve the theme directory (supports both local paths and npm packages) + const themeDir = await resolveThemeDir(themeIdentifier, ui); // Process each gallery directory let totalGalleries = 0; @@ -293,10 +322,16 @@ export async function build(options: BuildOptions, ui: ConsolaInstance): Promise return { processedGalleryCount: totalGalleries }; } catch (error) { - if (error instanceof Error && error.message.includes('Cannot find package')) { - ui.error( - `Theme package not found: ${options.theme || '@simple-photo-gallery/theme-modern'}. Make sure it's installed.`, - ); + if (error instanceof Error) { + if (error.message.includes('Cannot find package')) { + ui.error( + `Theme package not found: ${options.theme || '@simple-photo-gallery/theme-modern'}. Make sure it's installed.`, + ); + } else if (error.message.includes('Theme directory not found') || error.message.includes('package.json not found')) { + ui.error(error.message); + } else { + ui.error('Error building gallery'); + } } else { ui.error('Error building gallery'); } From 9a1d4a3cf3f30d528d2aaeefb1a7751d62699e07 Mon Sep 17 00:00:00 2001 From: rustoma Date: Sun, 28 Dec 2025 11:54:10 +0100 Subject: [PATCH 04/55] feat: add create-theme command and implementation for generating custom themes --- gallery/src/index.ts | 11 + gallery/src/modules/create-theme/index.ts | 132 +++ gallery/src/modules/create-theme/templates.ts | 946 ++++++++++++++++++ .../src/modules/create-theme/types/index.ts | 7 + 4 files changed, 1096 insertions(+) create mode 100644 gallery/src/modules/create-theme/index.ts create mode 100644 gallery/src/modules/create-theme/templates.ts create mode 100644 gallery/src/modules/create-theme/types/index.ts diff --git a/gallery/src/index.ts b/gallery/src/index.ts index e9f3aff..a8c973d 100644 --- a/gallery/src/index.ts +++ b/gallery/src/index.ts @@ -7,6 +7,7 @@ import { createConsola, LogLevels, type ConsolaInstance } from 'consola'; import { build } from './modules/build'; import { clean } from './modules/clean'; +import { createTheme } from './modules/create-theme'; import { init } from './modules/init'; import { telemetry } from './modules/telemetry'; import { TelemetryService } from './modules/telemetry/service'; @@ -193,6 +194,16 @@ program .option('-r, --recursive', 'Clean subdirectories recursively', false) .action(withCommandContext((options, ui) => clean(options, ui))); +program + .command('create-theme') + .description('Create a new theme template') + .argument('', 'Name of the theme to create') + .option('-p, --path ', 'Path where the theme should be created. Default: ./themes/') + .action(async (name, options, command) => { + const handler = withCommandContext((opts: { path?: string }, ui) => createTheme({ name, path: opts.path }, ui)); + await handler(options, command); + }); + program .command('telemetry') .description('Manage anonymous telemetry preferences. Use 1 to enable, 0 to disable, or no argument to check status') diff --git a/gallery/src/modules/create-theme/index.ts b/gallery/src/modules/create-theme/index.ts new file mode 100644 index 0000000..7851b92 --- /dev/null +++ b/gallery/src/modules/create-theme/index.ts @@ -0,0 +1,132 @@ +import fs from 'node:fs'; +import path from 'node:path'; + +import * as templates from './templates'; + +import type { CreateThemeOptions } from './types'; +import type { CommandResultSummary } from '../telemetry/types'; +import type { ConsolaInstance } from 'consola'; + +/** + * Validates the theme name + * @param name - Theme name to validate + * @returns true if valid, throws error if invalid + */ +function validateThemeName(name: string): boolean { + if (!name || name.trim().length === 0) { + throw new Error('Theme name cannot be empty'); + } + + // Check for invalid characters (basic validation) + if (!/^[a-z0-9-]+$/i.test(name)) { + throw new Error('Theme name can only contain letters, numbers, and hyphens'); + } + + return true; +} + +/** + * Creates a directory if it doesn't exist + * @param dirPath - Path to create + * @param ui - ConsolaInstance for logging + */ +async function ensureDirectory(dirPath: string, ui: ConsolaInstance): Promise { + try { + await fs.promises.mkdir(dirPath, { recursive: true }); + ui.debug(`Created directory: ${dirPath}`); + } catch (error) { + if (error instanceof Error && 'code' in error && error.code !== 'EEXIST') { + throw new Error(`Failed to create directory ${dirPath}: ${error.message}`); + } + } +} + +/** + * Writes a file with content + * @param filePath - Path to the file + * @param content - Content to write + * @param ui - ConsolaInstance for logging + */ +async function writeFile(filePath: string, content: string, ui: ConsolaInstance): Promise { + await fs.promises.writeFile(filePath, content, 'utf8'); + ui.debug(`Created file: ${filePath}`); +} + +/** + * Main function to create a new theme + * @param options - Options for creating the theme + * @param ui - ConsolaInstance for logging + * @returns CommandResultSummary + */ +export async function createTheme(options: CreateThemeOptions, ui: ConsolaInstance): Promise { + try { + // Validate theme name + validateThemeName(options.name); + + // Determine theme directory path + const themeDir = options.path || path.resolve(process.cwd(), 'themes', options.name); + + // Check if directory already exists + if (fs.existsSync(themeDir)) { + throw new Error(`Theme directory already exists: ${themeDir}`); + } + + ui.start(`Creating theme: ${options.name}`); + + // Create directory structure + await ensureDirectory(themeDir, ui); + await ensureDirectory(path.join(themeDir, 'src'), ui); + await ensureDirectory(path.join(themeDir, 'src', 'pages'), ui); + await ensureDirectory(path.join(themeDir, 'src', 'layouts'), ui); + await ensureDirectory(path.join(themeDir, 'src', 'lib'), ui); + await ensureDirectory(path.join(themeDir, 'src', 'utils'), ui); + await ensureDirectory(path.join(themeDir, 'public'), ui); + + // Generate all files + ui.debug('Generating theme files...'); + + // Root files + await writeFile(path.join(themeDir, 'package.json'), templates.getPackageJson(options.name), ui); + await writeFile(path.join(themeDir, 'astro.config.ts'), templates.getAstroConfig(), ui); + await writeFile(path.join(themeDir, 'tsconfig.json'), templates.getTsConfig(), ui); + await writeFile(path.join(themeDir, 'eslint.config.mjs'), templates.getEslintConfig(), ui); + await writeFile(path.join(themeDir, '.prettierrc.mjs'), templates.getPrettierConfig(), ui); + await writeFile(path.join(themeDir, '.prettierignore'), templates.getPrettierIgnore(), ui); + await writeFile(path.join(themeDir, '.gitignore'), templates.getGitIgnore(), ui); + await writeFile(path.join(themeDir, 'README.md'), templates.getReadme(options.name), ui); + + // Layout files + await writeFile(path.join(themeDir, 'src', 'layouts', 'MainHead.astro'), templates.getMainHead(), ui); + await writeFile(path.join(themeDir, 'src', 'layouts', 'MainLayout.astro'), templates.getMainLayout(), ui); + + // Page files + await writeFile(path.join(themeDir, 'src', 'pages', 'index.astro'), templates.getIndexPage(), ui); + + // Library files + await writeFile(path.join(themeDir, 'src', 'lib', 'markdown.ts'), templates.getMarkdownLib(), ui); + await writeFile( + path.join(themeDir, 'src', 'lib', 'photoswipe-video-plugin.ts'), + templates.getPhotoswipeVideoPlugin(), + ui, + ); + + // Utility files + await writeFile(path.join(themeDir, 'src', 'utils', 'index.ts'), templates.getUtilsIndex(), ui); + + ui.success(`Theme created successfully at: ${themeDir}`); + ui.info(`\nNext steps:`); + ui.info(`1. cd ${themeDir}`); + ui.info(`2. npm install`); + ui.info(`3. Customize your theme in src/pages/index.astro`); + ui.info(`4. Build a gallery with: spg build --theme ${themeDir}`); + + return { processedGalleryCount: 0 }; + } catch (error) { + if (error instanceof Error) { + ui.error(error.message); + } else { + ui.error('Failed to create theme'); + } + throw error; + } +} diff --git a/gallery/src/modules/create-theme/templates.ts b/gallery/src/modules/create-theme/templates.ts new file mode 100644 index 0000000..2eda20b --- /dev/null +++ b/gallery/src/modules/create-theme/templates.ts @@ -0,0 +1,946 @@ +/** + * Template generators for theme files + */ + +export function getPackageJson(themeName: string): string { + return `{ + "name": "@your-org/theme-${themeName}", + "version": "1.0.0", + "description": "Custom theme for Simple Photo Gallery", + "license": "MIT", + "type": "module", + "files": ["public", "src", "astro.config.ts", "tsconfig.json"], + "scripts": { + "dev": "astro dev", + "build": "astro build", + "preview": "astro preview", + "lint": "eslint . --ext .astro,.js,.jsx,.ts,.tsx", + "lint:fix": "eslint . --ext .astro,.js,.jsx,.ts,.tsx --fix", + "format": "prettier --check './**/*.{js,jsx,ts,tsx,css,scss,md,json,astro}'", + "format:fix": "prettier --write './**/*.{js,jsx,ts,tsx,css,scss,md,json,astro}'" + }, + "dependencies": { + "astro": "^5.11.0", + "astro-relative-links": "^0.4.2", + "blurhash": "^2.0.5", + "marked": "^16.4.0", + "photoswipe": "^5.4.4" + }, + "devDependencies": { + "@eslint/eslintrc": "^3.3.1", + "@eslint/js": "^9.30.1", + "@simple-photo-gallery/common": "^1.0.5", + "@types/photoswipe": "^4.1.6", + "@typescript-eslint/eslint-plugin": "^8.35.1", + "@typescript-eslint/parser": "^8.35.1", + "eslint": "^9.30.1", + "eslint-config-prettier": "^10.1.5", + "eslint-plugin-astro": "^1.3.1", + "eslint-plugin-import": "^2.31.0", + "prettier": "^3.4.2", + "prettier-plugin-astro": "^0.14.1", + "typescript": "^5.8.3" + } +} +`; +} + +export function getAstroConfig(): string { + return `import fs from 'node:fs'; +import path from 'node:path'; + +import { defineConfig } from 'astro/config'; +import relativeLinks from 'astro-relative-links'; + +import type { AstroIntegration } from 'astro'; + +// Dynamically import gallery.json from source path or fallback to local +const sourceGalleryPath = process.env.GALLERY_JSON_PATH; +if (!sourceGalleryPath) throw new Error('GALLERY_JSON_PATH environment variable is not set'); + +const outputDir = process.env.GALLERY_OUTPUT_DIR || sourceGalleryPath.replace('gallery.json', ''); + +/** + * Astro integration to prevent empty content collection files from being generated + */ +function preventEmptyContentFiles(): AstroIntegration { + return { + name: 'prevent-empty-content-files', + hooks: { + 'astro:build:done': ({ dir }) => { + const filesToRemove = ['content-assets.mjs', 'content-modules.mjs']; + for (const fileName of filesToRemove) { + const filePath = path.join(dir.pathname, fileName); + if (fs.existsSync(filePath)) { + try { + const content = fs.readFileSync(filePath, 'utf8'); + if (content.trim() === 'export default new Map();' || content.trim() === '') { + fs.unlinkSync(filePath); + } + } catch { + // Silently ignore errors + } + } + } + }, + }, + }; +} + +export default defineConfig({ + output: 'static', + outDir: outputDir + '/_build', + build: { + assets: 'assets', + assetsPrefix: 'gallery', + }, + integrations: [relativeLinks(), preventEmptyContentFiles()], + publicDir: 'public', + vite: { + define: { + 'process.env.GALLERY_JSON_PATH': JSON.stringify(sourceGalleryPath), + }, + build: { + cssCodeSplit: false, + rollupOptions: { + output: { + manualChunks: undefined, + }, + }, + }, + }, +}); +`; +} + +export function getTsConfig(): string { + return `{ + "extends": "astro/tsconfigs/strict", + "include": [".astro/types.d.ts", "**/*"], + "exclude": ["dist"], + "compilerOptions": { + "baseUrl": ".", + "paths": { + "@/*": ["src/*"] + } + } +} +`; +} + +export function getEslintConfig(): string { + return `import eslint from '@eslint/js'; +import eslintConfigPrettier from 'eslint-config-prettier'; +import eslintPluginAstro from 'eslint-plugin-astro'; +import globals from 'globals'; +import path from 'node:path'; +import tseslint from 'typescript-eslint'; + +const tseslintConfig = tseslint.config(eslint.configs.recommended, tseslint.configs.recommended); + +export default [ + { + ignores: ['node_modules', '.astro', '**/dist/*', '**/public/*', '**/_build/**'], + }, + ...tseslintConfig, + eslintConfigPrettier, + ...eslintPluginAstro.configs['flat/recommended'], + { + files: ['**/*.{js,mjs,cjs,ts,jsx,tsx,astro}'], + languageOptions: { + ecmaVersion: 2020, + globals: { + ...globals.browser, + ...globals.node, + }, + parserOptions: { + tsconfigRootDir: import.meta.dirname, + }, + }, + settings: { + 'import/resolver': { + alias: { + map: [['@', path.resolve(import.meta.dirname, './src')]], + extensions: ['.js', '.jsx', '.ts', '.d.ts', '.tsx', '.astro'], + }, + }, + }, + rules: { + 'no-console': ['warn', { allow: ['warn', 'error'] }], + '@typescript-eslint/no-explicit-any': ['warn'], + '@typescript-eslint/consistent-type-imports': 'warn', + }, + }, +]; +`; +} + +export function getPrettierConfig(): string { + return `/** + * @see https://prettier.io/docs/configuration + * @type {import("prettier").Config} + */ +const config = { + semi: true, + printWidth: 125, + tabWidth: 2, + useTabs: false, + singleQuote: true, + endOfLine: 'lf', + bracketSpacing: true, + trailingComma: 'all', + quoteProps: 'as-needed', + bracketSameLine: true, + plugins: ['prettier-plugin-astro'], + overrides: [ + { + files: '*.astro', + options: { + parser: 'astro', + }, + }, + ], +}; + +export default config; +`; +} + +export function getPrettierIgnore(): string { + return `**/node_modules/* +**/dist/* +**/.astro/* +**/_build/** +`; +} + +export function getGitIgnore(): string { + return `node_modules/ +dist/ +.astro/ +_build/ +*.log +.DS_Store +`; +} + +export function getReadme(themeName: string): string { + return `# ${themeName} Theme + +A custom theme for Simple Photo Gallery built with Astro. + +## Development + +\`\`\`bash +# Install dependencies +npm install + +# Start development server +npm run dev + +# Build for production +npm run build + +# Preview production build +npm run preview +\`\`\` + +## Customization + +Edit \`src/pages/index.astro\` to customize your theme. This is the main entry point that receives gallery data and renders your gallery. + +## Building Galleries + +To use this theme when building a gallery: + +\`\`\`bash +# Using local path +spg build --theme ./themes/${themeName} + +# Or if published to npm +spg build --theme @your-org/theme-${themeName} +\`\`\` + +## Structure + +- \`src/pages/index.astro\` - Main gallery page +- \`src/layouts/\` - Layout components (MainHead, MainLayout) +- \`src/lib/\` - Utility libraries (markdown, photoswipe-video-plugin) +- \`src/utils/\` - Helper functions for paths and resources +- \`public/\` - Static assets +`; +} + +export function getMainHead(): string { + return `--- +import type { GalleryMetadata } from '@simple-photo-gallery/common/src/gallery'; + +interface Props { + title: string; + description?: string; + url?: string; + thumbsBaseUrl?: string; + metadata?: GalleryMetadata; +} + +const { title, description, url, thumbsBaseUrl, metadata } = Astro.props; +--- + + + + + {title} + + + + {/* Basic SEO */} + + {metadata?.keywords && } + {metadata?.author && } + {metadata?.canonicalUrl || (url && )} + + {/* Open Graph */} + + + {metadata?.image && } + {metadata?.ogUrl || (url && )} + + {/* Twitter */} + + + + {metadata?.image && } + +`; +} + +export function getMainLayout(): string { + return `--- +import MainHead from '@/layouts/MainHead'; + +import type { GalleryMetadata } from '@simple-photo-gallery/common/src/gallery'; + +interface Props { + title: string; + description?: string; + url?: string; + thumbsBaseUrl?: string; + metadata?: GalleryMetadata; + analyticsScript?: string; +} + +const { title, description, metadata, url, thumbsBaseUrl, analyticsScript } = Astro.props; +--- + + + + + + + + {analyticsScript && } + + + + +`; +} + +export function getIndexPage(): string { + return `--- +import fs from 'node:fs'; + +import MainLayout from '@/layouts/MainLayout'; +import { getPhotoPath, getThumbnailPath } from '@/utils'; +import { renderMarkdown } from '@/lib/markdown'; + +import type { GalleryData } from '@simple-photo-gallery/common/src/gallery'; + +// Read gallery.json from the path provided by the build process +const galleryJsonPath = process.env.GALLERY_JSON_PATH || './gallery.json'; +const galleryData = JSON.parse(fs.readFileSync(galleryJsonPath, 'utf8')); +const gallery = galleryData as GalleryData; + +const { title, description, sections, mediaBaseUrl, thumbsBaseUrl, headerImage, headerImageBlurHash } = gallery; + +// Render description markdown if present +const descriptionHtml = description ? await renderMarkdown(description) : ''; +--- + + +
+
+

{title}

+ {descriptionHtml &&
} +
+ + {/* Render gallery sections */} + {sections.map((section) => ( +
+ {section.title &&

{section.title}

} + {section.description &&

{section.description}

} + +
+ {section.images.map((image) => { + const imagePath = getPhotoPath(image.filename, mediaBaseUrl, image.url); + const thumbnailPath = getThumbnailPath( + image.thumbnail?.filename || image.filename, + thumbsBaseUrl, + image.thumbnail?.baseUrl, + ); + + return ( + + {image.caption + {image.caption && {image.caption}} + + ); + })} +
+
+ ))} +
+ + + + + +`; +} + +export function getMarkdownLib(): string { + return `import { marked } from 'marked'; + +// Configure marked to only allow specific formatting options +const renderer = new marked.Renderer(); + +// Disable headings by rendering them as paragraphs +renderer.heading = ({ text }: { text: string }) => { + return '

' + text + '

\\n'; +}; + +// Disable images +renderer.image = () => ''; + +// Disable HTML +renderer.html = () => ''; + +// Disable tables +renderer.table = () => ''; +renderer.tablerow = () => ''; +renderer.tablecell = () => ''; + +// Configure marked options +marked.use({ + renderer: renderer, + breaks: true, + gfm: true, +}); + +/** + * Renders markdown with limited formatting options. + * Supported: paragraphs, bold, italic, lists, code blocks, blockquotes, links + * Disabled: headings (rendered as paragraphs), images, HTML, tables + */ +export async function renderMarkdown(markdown: string): Promise { + if (!markdown) return ''; + return await marked.parse(markdown); +} +`; +} + +export function getPhotoswipeVideoPlugin(): string { + return `import type PhotoSwipe from 'photoswipe'; +import type PhotoSwipeLightbox from 'photoswipe/lightbox'; + +interface Slide { + content: Content; + height: number; + currZoomLevel: number; + bounds: { center: { y: number } }; + placeholder?: { element: HTMLElement }; + isActive: boolean; +} + +interface Content { + data: SlideData; + element?: HTMLVideoElement | HTMLImageElement | HTMLDivElement; + state?: string; + type?: string; + isAttached?: boolean; + onLoaded?: () => void; + appendImage?: () => void; + slide?: Slide; + _videoPosterImg?: HTMLImageElement; +} + +interface SlideData { + type?: string; + msrc?: string; + videoSrc?: string; + videoSources?: Array<{ src: string; type: string }>; +} + +interface VideoPluginOptions { + videoAttributes?: Record; + autoplay?: boolean; + preventDragOffset?: number; +} + +interface EventData { + content?: Content; + slide?: Slide; + width?: number; + height?: number; + originalEvent?: PointerEvent; + preventDefault?: () => void; +} + +const defaultOptions: VideoPluginOptions = { + videoAttributes: { controls: '', playsinline: '', preload: 'auto' }, + autoplay: true, + preventDragOffset: 40, +}; + +/** + * Check if slide has video content + */ +function isVideoContent(content: Content | Slide): boolean { + return content && 'data' in content && content.data && content.data.type === 'video'; +} + +class VideoContentSetup { + private options: VideoPluginOptions; + + constructor(lightbox: PhotoSwipeLightbox, options: VideoPluginOptions) { + this.options = options; + + this.initLightboxEvents(lightbox); + lightbox.on('init', () => { + if (lightbox.pswp) { + this.initPswpEvents(lightbox.pswp); + } + }); + } + + private initLightboxEvents(lightbox: PhotoSwipeLightbox): void { + lightbox.on('contentLoad', (data: unknown) => this.onContentLoad(data as EventData)); + lightbox.on('contentDestroy', (data: unknown) => this.onContentDestroy(data as { content: Content })); + lightbox.on('contentActivate', (data: unknown) => this.onContentActivate(data as { content: Content })); + lightbox.on('contentDeactivate', (data: unknown) => this.onContentDeactivate(data as { content: Content })); + lightbox.on('contentAppend', (data: unknown) => this.onContentAppend(data as EventData)); + lightbox.on('contentResize', (data: unknown) => this.onContentResize(data as EventData)); + + lightbox.addFilter('isKeepingPlaceholder', (value: unknown, ...args: unknown[]) => + this.isKeepingPlaceholder(value as boolean, args[0] as Content), + ); + lightbox.addFilter('isContentZoomable', (value: unknown, ...args: unknown[]) => + this.isContentZoomable(value as boolean, args[0] as Content), + ); + lightbox.addFilter('useContentPlaceholder', (value: unknown, ...args: unknown[]) => + this.useContentPlaceholder(value as boolean, args[0] as Content), + ); + + lightbox.addFilter('domItemData', (value: unknown, ...args: unknown[]) => { + const itemData = value as Record; + const linkEl = args[1] as HTMLAnchorElement; + + if (itemData.type === 'video' && linkEl) { + if (linkEl.dataset.pswpVideoSources) { + itemData.videoSources = JSON.parse(linkEl.dataset.pswpVideoSources); + } else if (linkEl.dataset.pswpVideoSrc) { + itemData.videoSrc = linkEl.dataset.pswpVideoSrc; + } else { + itemData.videoSrc = linkEl.href; + } + } + return itemData; + }); + } + + private initPswpEvents(pswp: PhotoSwipe): void { + pswp.on('pointerDown', (data: unknown) => { + const e = data as EventData; + const slide = pswp.currSlide as Slide | undefined; + if (slide && isVideoContent(slide) && this.options.preventDragOffset) { + const origEvent = e.originalEvent; + if (origEvent && origEvent.type === 'pointerdown') { + const videoHeight = Math.ceil(slide.height * slide.currZoomLevel); + const verticalEnding = videoHeight + slide.bounds.center.y; + const pointerYPos = origEvent.pageY - pswp.offset.y; + if (pointerYPos > verticalEnding - this.options.preventDragOffset! && pointerYPos < verticalEnding) { + e.preventDefault?.(); + } + } + } + }); + + pswp.on('appendHeavy', (data: unknown) => { + const e = data as EventData; + if (e.slide && isVideoContent(e.slide) && !e.slide.isActive) { + e.preventDefault?.(); + } + }); + + pswp.on('close', () => { + const slide = pswp.currSlide as Slide | undefined; + if (slide && isVideoContent(slide.content)) { + if (!pswp.options.showHideAnimationType || pswp.options.showHideAnimationType === 'zoom') { + pswp.options.showHideAnimationType = 'fade'; + } + this.pauseVideo(slide.content); + } + }); + } + + private onContentDestroy({ content }: { content: Content }): void { + if (isVideoContent(content) && content._videoPosterImg) { + const handleLoad = () => { + if (content._videoPosterImg) { + content._videoPosterImg.removeEventListener('error', handleError); + } + }; + const handleError = () => { + // Error handler + }; + + content._videoPosterImg.addEventListener('load', handleLoad); + content._videoPosterImg.addEventListener('error', handleError); + content._videoPosterImg = undefined; + } + } + + private onContentResize(e: EventData): void { + if (e.content && isVideoContent(e.content)) { + e.preventDefault?.(); + + const width = e.width!; + const height = e.height!; + const content = e.content; + + if (content.element) { + content.element.style.width = width + 'px'; + content.element.style.height = height + 'px'; + } + + if (content.slide && content.slide.placeholder) { + const placeholderElStyle = content.slide.placeholder.element.style; + placeholderElStyle.transform = 'none'; + placeholderElStyle.width = width + 'px'; + placeholderElStyle.height = height + 'px'; + } + } + } + + private isKeepingPlaceholder(isZoomable: boolean, content: Content): boolean { + if (isVideoContent(content)) { + return false; + } + return isZoomable; + } + + private isContentZoomable(isZoomable: boolean, content: Content): boolean { + if (isVideoContent(content)) { + return false; + } + return isZoomable; + } + + private onContentActivate({ content }: { content: Content }): void { + if (isVideoContent(content) && this.options.autoplay) { + this.playVideo(content); + } + } + + private onContentDeactivate({ content }: { content: Content }): void { + if (isVideoContent(content)) { + this.pauseVideo(content); + } + } + + private onContentAppend(e: EventData): void { + if (e.content && isVideoContent(e.content)) { + e.preventDefault?.(); + e.content.isAttached = true; + e.content.appendImage?.(); + } + } + + private onContentLoad(e: EventData): void { + const content = e.content!; + + if (!isVideoContent(content)) { + return; + } + + e.preventDefault?.(); + + if (content.element) { + return; + } + + content.state = 'loading'; + content.type = 'video'; + + content.element = document.createElement('video'); + + if (this.options.videoAttributes) { + for (const key in this.options.videoAttributes) { + content.element.setAttribute(key, this.options.videoAttributes[key] || ''); + } + } + + content.element.setAttribute('poster', content.data.msrc || ''); + + this.preloadVideoPoster(content, content.data.msrc); + + content.element.style.position = 'absolute'; + content.element.style.left = '0'; + content.element.style.top = '0'; + + if (content.data.videoSources) { + for (const source of content.data.videoSources) { + const sourceEl = document.createElement('source'); + sourceEl.src = source.src; + sourceEl.type = source.type; + content.element.append(sourceEl); + } + } else if (content.data.videoSrc) { + content.element.src = content.data.videoSrc; + } + } + + private preloadVideoPoster(content: Content, src?: string): void { + if (!content._videoPosterImg && src) { + content._videoPosterImg = new Image(); + content._videoPosterImg.src = src; + if (content._videoPosterImg.complete) { + content.onLoaded?.(); + } else { + content._videoPosterImg.addEventListener('load', () => { + content.onLoaded?.(); + }); + content._videoPosterImg.addEventListener('error', () => { + content.onLoaded?.(); + }); + } + } + } + + private playVideo(content: Content): void { + if (content.element) { + (content.element as HTMLVideoElement).play(); + } + } + + private pauseVideo(content: Content): void { + if (content.element) { + (content.element as HTMLVideoElement).pause(); + } + } + + private useContentPlaceholder(usePlaceholder: boolean, content: Content): boolean { + if (isVideoContent(content)) { + return true; + } + return usePlaceholder; + } +} + +class PhotoSwipeVideoPlugin { + constructor(lightbox: PhotoSwipeLightbox, options: VideoPluginOptions = {}) { + new VideoContentSetup(lightbox, { + ...defaultOptions, + ...options, + }); + } +} + +export default PhotoSwipeVideoPlugin; +export type { VideoPluginOptions }; +`; +} + +export function getUtilsIndex(): string { + return `import path from 'node:path'; + +/** + * 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 + * @returns The normalized path relative to the gallery root directory + */ +export const getRelativePath = (resourcePath: string) => { + const galleryConfigPath = path.resolve(process.env.GALLERY_JSON_PATH || ''); + const galleryConfigDir = path.dirname(galleryConfigPath); + + const absoluteResourcePath = path.resolve(path.join(galleryConfigDir, resourcePath)); + const baseDir = path.dirname(galleryConfigDir); + + return path.relative(baseDir, absoluteResourcePath); +}; + +/** + * 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 + */ +export const getThumbnailPath = (resourcePath: string, thumbsBaseUrl?: string, thumbnailBaseUrl?: string) => { + // If thumbnail-specific baseUrl is provided, use it and combine with the path + if (thumbnailBaseUrl) { + return \`\${thumbnailBaseUrl}/\${resourcePath}\`; + } + // Otherwise, use the gallery-level thumbsBaseUrl if provided + return thumbsBaseUrl ? \`\${thumbsBaseUrl}/\${resourcePath}\` : \`gallery/images/\${path.basename(resourcePath)}\`; +}; + +/** + * 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 + */ +export const getPhotoPath = (filename: string, mediaBaseUrl?: string, url?: string) => { + // If url is provided, always use it regardless of base URL or path + if (url) { + return url; + } + + return mediaBaseUrl ? \`\${mediaBaseUrl}/\${filename}\` : filename; +}; + +/** + * 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 + */ +export const getSubgalleryThumbnailPath = (subgalleryHeaderImagePath: string) => { + const photoBasename = path.basename(subgalleryHeaderImagePath); + const subgalleryFolderName = path.basename(path.dirname(subgalleryHeaderImagePath)); + + return path.join(subgalleryFolderName, 'gallery', 'thumbnails', photoBasename); +}; +`; +} diff --git a/gallery/src/modules/create-theme/types/index.ts b/gallery/src/modules/create-theme/types/index.ts new file mode 100644 index 0000000..4e06d65 --- /dev/null +++ b/gallery/src/modules/create-theme/types/index.ts @@ -0,0 +1,7 @@ +/** Options for creating a new theme */ +export interface CreateThemeOptions { + /** Name of the theme to create */ + name: string; + /** Path where the theme should be created. Default: ./themes/ */ + path?: string; +} From cd9f65aac6a4f8272635423f108aeabee1597a58 Mon Sep 17 00:00:00 2001 From: rustoma Date: Sun, 28 Dec 2025 12:03:15 +0100 Subject: [PATCH 05/55] feat: enhance createTheme function to support custom theme paths and prevent overwriting existing themes --- gallery/src/modules/create-theme/index.ts | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/gallery/src/modules/create-theme/index.ts b/gallery/src/modules/create-theme/index.ts index 7851b92..49dfe4e 100644 --- a/gallery/src/modules/create-theme/index.ts +++ b/gallery/src/modules/create-theme/index.ts @@ -1,5 +1,6 @@ import fs from 'node:fs'; import path from 'node:path'; +import process from 'node:process'; import * as templates from './templates'; @@ -64,11 +65,24 @@ export async function createTheme(options: CreateThemeOptions, ui: ConsolaInstan validateThemeName(options.name); // Determine theme directory path - const themeDir = options.path || path.resolve(process.cwd(), 'themes', options.name); + let themeDir: string; + if (options.path) { + // If a custom path is provided, use it as-is + themeDir = path.resolve(options.path); + } else { + // Default: create in ./themes/ directory + const themesBaseDir = path.resolve(process.cwd(), 'themes'); + themeDir = path.join(themesBaseDir, options.name); + + // Ensure the themes base directory exists (but don't overwrite anything) + if (!fs.existsSync(themesBaseDir)) { + await ensureDirectory(themesBaseDir, ui); + } + } - // Check if directory already exists + // Check if directory already exists - prevent overwriting existing themes if (fs.existsSync(themeDir)) { - throw new Error(`Theme directory already exists: ${themeDir}`); + throw new Error(`Theme directory already exists: ${themeDir}. Cannot overwrite existing theme.`); } ui.start(`Creating theme: ${options.name}`); From cb2573cbc23b80e4c75ac122101735fbccefd706 Mon Sep 17 00:00:00 2001 From: rustoma Date: Sun, 28 Dec 2025 12:21:22 +0100 Subject: [PATCH 06/55] feat: add gallery script to package.json and implement monorepo root detection in createTheme function --- gallery/src/modules/create-theme/index.ts | 35 ++++++++++++++++++++++- package.json | 3 ++ 2 files changed, 37 insertions(+), 1 deletion(-) diff --git a/gallery/src/modules/create-theme/index.ts b/gallery/src/modules/create-theme/index.ts index 49dfe4e..68d214e 100644 --- a/gallery/src/modules/create-theme/index.ts +++ b/gallery/src/modules/create-theme/index.ts @@ -8,6 +8,37 @@ import type { CreateThemeOptions } from './types'; import type { CommandResultSummary } from '../telemetry/types'; import type { ConsolaInstance } from 'consola'; +/** + * Find the nearest ancestor directory (including the starting directory) that looks like a monorepo root + * by checking for a package.json with a "workspaces" field. + * + * This avoids surprising behavior when the CLI is executed from within a workspace package (e.g. ./gallery), + * but the user expects themes to be created under the monorepo root (e.g. ./themes). + */ +function findMonorepoRoot(startDir: string): string | undefined { + let dir = path.resolve(startDir); + + while (true) { + const pkgPath = path.join(dir, 'package.json'); + if (fs.existsSync(pkgPath)) { + try { + const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8')) as { workspaces?: unknown }; + if (pkg && typeof pkg === 'object' && 'workspaces' in pkg) { + return dir; + } + } catch { + // Ignore JSON parse errors and continue searching upwards + } + } + + const parent = path.dirname(dir); + if (parent === dir) { + return undefined; + } + dir = parent; + } +} + /** * Validates the theme name * @param name - Theme name to validate @@ -71,7 +102,9 @@ export async function createTheme(options: CreateThemeOptions, ui: ConsolaInstan themeDir = path.resolve(options.path); } else { // Default: create in ./themes/ directory - const themesBaseDir = path.resolve(process.cwd(), 'themes'); + const monorepoRoot = findMonorepoRoot(process.cwd()); + const baseDir = monorepoRoot ?? process.cwd(); + const themesBaseDir = path.resolve(baseDir, 'themes'); themeDir = path.join(themesBaseDir, options.name); // Ensure the themes base directory exists (but don't overwrite anything) diff --git a/package.json b/package.json index 32d5be3..1fe9166 100644 --- a/package.json +++ b/package.json @@ -2,6 +2,9 @@ "name": "@simple-photo-gallery/workspace", "version": "1.0.0", "private": true, + "scripts": { + "gallery": "yarn workspace simple-photo-gallery gallery" + }, "workspaces": { "packages": [ "common", From 297da7b31aef5e1134c05a306fe2042e25d601a4 Mon Sep 17 00:00:00 2001 From: rustoma Date: Sun, 28 Dec 2025 12:32:25 +0100 Subject: [PATCH 07/55] feat: update package.json generation to use theme name directly and add peerDependencies for common package --- gallery/src/modules/create-theme/templates.ts | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/gallery/src/modules/create-theme/templates.ts b/gallery/src/modules/create-theme/templates.ts index 2eda20b..d3a50d0 100644 --- a/gallery/src/modules/create-theme/templates.ts +++ b/gallery/src/modules/create-theme/templates.ts @@ -4,7 +4,7 @@ export function getPackageJson(themeName: string): string { return `{ - "name": "@your-org/theme-${themeName}", + "name": "${themeName}", "version": "1.0.0", "description": "Custom theme for Simple Photo Gallery", "license": "MIT", @@ -26,6 +26,9 @@ export function getPackageJson(themeName: string): string { "marked": "^16.4.0", "photoswipe": "^5.4.4" }, + "peerDependencies": { + "@simple-photo-gallery/common": "^1.0.5" + }, "devDependencies": { "@eslint/eslintrc": "^3.3.1", "@eslint/js": "^9.30.1", From 35a393ead2401034f028d1f87c67fbcba02e389a Mon Sep 17 00:00:00 2001 From: rustoma Date: Sun, 28 Dec 2025 13:03:02 +0100 Subject: [PATCH 08/55] feat: update yarn.lock with new theme dependencies and modify createTheme instructions for clarity --- gallery/src/modules/create-theme/index.ts | 5 +- gallery/src/modules/create-theme/templates.ts | 57 ++++++++++++------- yarn.lock | 29 +++++++++- 3 files changed, 69 insertions(+), 22 deletions(-) diff --git a/gallery/src/modules/create-theme/index.ts b/gallery/src/modules/create-theme/index.ts index 68d214e..71aa34c 100644 --- a/gallery/src/modules/create-theme/index.ts +++ b/gallery/src/modules/create-theme/index.ts @@ -163,9 +163,10 @@ export async function createTheme(options: CreateThemeOptions, ui: ConsolaInstan ui.success(`Theme created successfully at: ${themeDir}`); ui.info(`\nNext steps:`); ui.info(`1. cd ${themeDir}`); - ui.info(`2. npm install`); + ui.info(`2. yarn install`); ui.info(`3. Customize your theme in src/pages/index.astro`); - ui.info(`4. Build a gallery with: spg build --theme ${themeDir}`); + ui.info(`4. Initialize a gallery (run from directory with your images): spg init -p `); + ui.info(`5. Build a gallery with your theme: spg build --theme ${themeDir} -g `); return { processedGalleryCount: 0 }; } catch (error) { diff --git a/gallery/src/modules/create-theme/templates.ts b/gallery/src/modules/create-theme/templates.ts index d3a50d0..4e9e046 100644 --- a/gallery/src/modules/create-theme/templates.ts +++ b/gallery/src/modules/create-theme/templates.ts @@ -124,7 +124,8 @@ export function getTsConfig(): string { "compilerOptions": { "baseUrl": ".", "paths": { - "@/*": ["src/*"] + "@/*": ["src/*"], + "@simple-photo-gallery/common/src/*": ["../../common/src/*"] } } } @@ -236,16 +237,16 @@ A custom theme for Simple Photo Gallery built with Astro. \`\`\`bash # Install dependencies -npm install +yarn install # Start development server -npm run dev +yarn dev # Build for production -npm run build +yarn build # Preview production build -npm run preview +yarn preview \`\`\` ## Customization @@ -257,11 +258,17 @@ Edit \`src/pages/index.astro\` to customize your theme. This is the main entry p To use this theme when building a gallery: \`\`\`bash -# Using local path -spg build --theme ./themes/${themeName} +# 1. Initialize a gallery from your images folder +spg init -p -g + +# 2. Generate thumbnails (optional but recommended) +spg thumbnails -g + +# 3. Build the gallery with your theme +spg build --theme ./themes/${themeName} -g # Or if published to npm -spg build --theme @your-org/theme-${themeName} +spg build --theme @your-org/theme-${themeName} -g \`\`\` ## Structure @@ -319,7 +326,7 @@ const { title, description, url, thumbsBaseUrl, metadata } = Astro.props; export function getMainLayout(): string { return `--- -import MainHead from '@/layouts/MainHead'; +import MainHead from '@/layouts/MainHead.astro'; import type { GalleryMetadata } from '@simple-photo-gallery/common/src/gallery'; @@ -367,7 +374,7 @@ export function getIndexPage(): string { return `--- import fs from 'node:fs'; -import MainLayout from '@/layouts/MainLayout'; +import MainLayout from '@/layouts/MainLayout.astro'; import { getPhotoPath, getThumbnailPath } from '@/utils'; import { renderMarkdown } from '@/lib/markdown'; @@ -378,7 +385,7 @@ const galleryJsonPath = process.env.GALLERY_JSON_PATH || './gallery.json'; const galleryData = JSON.parse(fs.readFileSync(galleryJsonPath, 'utf8')); const gallery = galleryData as GalleryData; -const { title, description, sections, mediaBaseUrl, thumbsBaseUrl, headerImage, headerImageBlurHash } = gallery; +const { title, description, sections, mediaBaseUrl, thumbsBaseUrl } = gallery; // Render description markdown if present const descriptionHtml = description ? await renderMarkdown(description) : ''; @@ -400,11 +407,16 @@ const descriptionHtml = description ? await renderMarkdown(description) : '';
{section.images.map((image) => { const imagePath = getPhotoPath(image.filename, mediaBaseUrl, image.url); - const thumbnailPath = getThumbnailPath( - image.thumbnail?.filename || image.filename, - thumbsBaseUrl, - image.thumbnail?.baseUrl, - ); + const thumbnailPath = image.thumbnail + ? getThumbnailPath(image.thumbnail.path, thumbsBaseUrl, image.thumbnail.baseUrl) + : imagePath; + + const thumbnailSrcSet = image.thumbnail + ? getThumbnailPath(image.thumbnail.path, thumbsBaseUrl, image.thumbnail.baseUrl) + + ' 1x, ' + + getThumbnailPath(image.thumbnail.pathRetina, thumbsBaseUrl, image.thumbnail.baseUrl) + + ' 2x' + : undefined; return ( - {image.caption - {image.caption && {image.caption}} + {image.alt + {image.alt && {image.alt}} ); })} diff --git a/yarn.lock b/yarn.lock index 910255e..23f7436 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1652,7 +1652,7 @@ __metadata: languageName: node linkType: hard -"@simple-photo-gallery/common@npm:1.0.5, @simple-photo-gallery/common@workspace:common": +"@simple-photo-gallery/common@npm:1.0.5, @simple-photo-gallery/common@npm:^1.0.5, @simple-photo-gallery/common@workspace:common": version: 0.0.0-use.local resolution: "@simple-photo-gallery/common@workspace:common" dependencies: @@ -7117,6 +7117,33 @@ __metadata: languageName: node linkType: hard +"my-theme@workspace:themes/my-theme": + version: 0.0.0-use.local + resolution: "my-theme@workspace:themes/my-theme" + dependencies: + "@eslint/eslintrc": "npm:^3.3.1" + "@eslint/js": "npm:^9.30.1" + "@simple-photo-gallery/common": "npm:^1.0.5" + "@types/photoswipe": "npm:^4.1.6" + "@typescript-eslint/eslint-plugin": "npm:^8.35.1" + "@typescript-eslint/parser": "npm:^8.35.1" + astro: "npm:^5.11.0" + astro-relative-links: "npm:^0.4.2" + blurhash: "npm:^2.0.5" + eslint: "npm:^9.30.1" + eslint-config-prettier: "npm:^10.1.5" + eslint-plugin-astro: "npm:^1.3.1" + eslint-plugin-import: "npm:^2.31.0" + marked: "npm:^16.4.0" + photoswipe: "npm:^5.4.4" + prettier: "npm:^3.4.2" + prettier-plugin-astro: "npm:^0.14.1" + typescript: "npm:^5.8.3" + peerDependencies: + "@simple-photo-gallery/common": ^1.0.5 + languageName: unknown + linkType: soft + "mz@npm:^2.7.0": version: 2.7.0 resolution: "mz@npm:2.7.0" From d8b70ea3225c37c9040989dc55692474cf65ec21 Mon Sep 17 00:00:00 2001 From: rustoma Date: Sun, 28 Dec 2025 13:05:51 +0100 Subject: [PATCH 09/55] feat: add support for dynamic header images in theme templates and enhance layout with responsive image handling --- gallery/src/modules/create-theme/templates.ts | 202 +++++++++++++++++- 1 file changed, 194 insertions(+), 8 deletions(-) diff --git a/gallery/src/modules/create-theme/templates.ts b/gallery/src/modules/create-theme/templates.ts index 4e9e046..97aab86 100644 --- a/gallery/src/modules/create-theme/templates.ts +++ b/gallery/src/modules/create-theme/templates.ts @@ -291,9 +291,16 @@ interface Props { url?: string; thumbsBaseUrl?: string; metadata?: GalleryMetadata; + headerImageBasename?: string; } -const { title, description, url, thumbsBaseUrl, metadata } = Astro.props; +const { title, description, url, thumbsBaseUrl, metadata, headerImageBasename } = 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'; --- @@ -320,12 +327,37 @@ const { title, description, url, thumbsBaseUrl, metadata } = Astro.props; {metadata?.image && } + + {headerImageBasename && ( + <> + + + + )} `; } export function getMainLayout(): string { return `--- +import path from 'node:path'; + import MainHead from '@/layouts/MainHead.astro'; import type { GalleryMetadata } from '@simple-photo-gallery/common/src/gallery'; @@ -337,14 +369,18 @@ interface Props { thumbsBaseUrl?: string; metadata?: GalleryMetadata; analyticsScript?: string; + headerImage?: string; } -const { title, description, metadata, url, thumbsBaseUrl, analyticsScript } = Astro.props; +const { title, description, metadata, url, thumbsBaseUrl, analyticsScript, headerImage } = Astro.props; + +// Extract basename from headerImage filename +const headerImageBasename = headerImage ? path.basename(headerImage, path.extname(headerImage)) : undefined; --- - + @@ -385,18 +421,36 @@ const galleryJsonPath = process.env.GALLERY_JSON_PATH || './gallery.json'; const galleryData = JSON.parse(fs.readFileSync(galleryJsonPath, 'utf8')); const gallery = galleryData as GalleryData; -const { title, description, sections, mediaBaseUrl, thumbsBaseUrl } = gallery; +const { title, description, sections, mediaBaseUrl, thumbsBaseUrl, headerImage, headerImageBlurHash } = gallery; // Render description markdown if present const descriptionHtml = description ? await renderMarkdown(description) : ''; + +// Get header image path if present +const headerImagePath = headerImage ? getPhotoPath(headerImage, mediaBaseUrl) : undefined; --- - -
-
+ + {headerImagePath ? ( +
+
+ {headerImageBlurHash && } + {title} +
+
+
+

{title}

+ {descriptionHtml &&
} +
+
+ ) : ( +

{title}

- {descriptionHtml &&
} + {descriptionHtml &&
}
+ )} + +
{/* Render gallery sections */} {sections.map((section) => ( @@ -444,6 +498,39 @@ const descriptionHtml = description ? await renderMarkdown(description) : '';
+{headerImageBlurHash && ( + +)} + + + +`; +} + export function getIndexPage(): string { return `--- import fs from 'node:fs'; import MainLayout from '@/layouts/MainLayout.astro'; +import Hero from '@/components/Hero.astro'; import { getPhotoPath, getThumbnailPath } from '@/utils'; -import { renderMarkdown } from '@/lib/markdown'; import type { GalleryData } from '@simple-photo-gallery/common/src/gallery'; @@ -422,33 +687,17 @@ const galleryData = JSON.parse(fs.readFileSync(galleryJsonPath, 'utf8')); const gallery = galleryData as GalleryData; const { title, description, sections, mediaBaseUrl, thumbsBaseUrl, headerImage, headerImageBlurHash } = gallery; - -// Render description markdown if present -const descriptionHtml = description ? await renderMarkdown(description) : ''; - -// Get header image path if present -const headerImagePath = headerImage ? getPhotoPath(headerImage, mediaBaseUrl) : undefined; --- - {headerImagePath ? ( -
-
- {headerImageBlurHash && } - {title} -
-
-
-

{title}

- {descriptionHtml &&
} -
-
- ) : ( -
-

{title}

- {descriptionHtml &&
} -
- )} +
@@ -498,39 +747,6 @@ const headerImagePath = headerImage ? getPhotoPath(headerImage, mediaBaseUrl) :
-{headerImageBlurHash && ( - -)} - - - -`; -} - -export function getIndexPage(): string { - return `--- -import fs from 'node:fs'; - -import MainLayout from '@/layouts/MainLayout.astro'; -import Hero from '@/components/Hero.astro'; -import { getPhotoPath, getThumbnailPath } from '@/utils'; - -import type { GalleryData } from '@simple-photo-gallery/common'; - -// Read gallery.json from the path provided by the build process -const galleryJsonPath = process.env.GALLERY_JSON_PATH || './gallery.json'; -const galleryData = JSON.parse(fs.readFileSync(galleryJsonPath, 'utf8')); -const gallery = galleryData as GalleryData; - -const { title, description, sections, mediaBaseUrl, thumbsBaseUrl, headerImage, headerImageBlurHash } = gallery; ---- - - - - -
- - {/* Render gallery sections */} - {sections.map((section) => ( -
- {section.title &&

{section.title}

} - {section.description &&

{section.description}

} - -
- {section.images.map((image) => { - const imagePath = getPhotoPath(image.filename, mediaBaseUrl, image.url); - const thumbnailPath = image.thumbnail - ? getThumbnailPath(image.thumbnail.path, thumbsBaseUrl, image.thumbnail.baseUrl) - : imagePath; - - const thumbnailSrcSet = image.thumbnail - ? getThumbnailPath(image.thumbnail.path, thumbsBaseUrl, image.thumbnail.baseUrl) + - ' 1x, ' + - getThumbnailPath(image.thumbnail.pathRetina, thumbsBaseUrl, image.thumbnail.baseUrl) + - ' 2x' - : undefined; - - return ( - - {image.alt - {image.alt && {image.alt}} - - ); - })} -
-
- ))} -
- - - - - -`; -} - -export function getMarkdownLib(): string { - return `import { marked } from 'marked'; - -// Configure marked to only allow specific formatting options -const renderer = new marked.Renderer(); - -// Disable headings by rendering them as paragraphs -renderer.heading = ({ text }: { text: string }) => { - return '

' + text + '

\\n'; -}; - -// Disable images -renderer.image = () => ''; - -// Disable HTML -renderer.html = () => ''; - -// Disable tables -renderer.table = () => ''; -renderer.tablerow = () => ''; -renderer.tablecell = () => ''; - -// Configure marked options -marked.use({ - renderer: renderer, - breaks: true, - gfm: true, -}); - -/** - * Renders markdown with limited formatting options. - * Supported: paragraphs, bold, italic, lists, code blocks, blockquotes, links - * Disabled: headings (rendered as paragraphs), images, HTML, tables - */ -export async function renderMarkdown(markdown: string): Promise { - if (!markdown) return ''; - return await marked.parse(markdown); -} -`; -} - -export function getPhotoswipeVideoPlugin(): string { - return `import type PhotoSwipe from 'photoswipe'; -import type PhotoSwipeLightbox from 'photoswipe/lightbox'; - -interface Slide { - content: Content; - height: number; - currZoomLevel: number; - bounds: { center: { y: number } }; - placeholder?: { element: HTMLElement }; - isActive: boolean; -} - -interface Content { - data: SlideData; - element?: HTMLVideoElement | HTMLImageElement | HTMLDivElement; - state?: string; - type?: string; - isAttached?: boolean; - onLoaded?: () => void; - appendImage?: () => void; - slide?: Slide; - _videoPosterImg?: HTMLImageElement; -} - -interface SlideData { - type?: string; - msrc?: string; - videoSrc?: string; - videoSources?: Array<{ src: string; type: string }>; -} - -interface VideoPluginOptions { - videoAttributes?: Record; - autoplay?: boolean; - preventDragOffset?: number; -} - -interface EventData { - content?: Content; - slide?: Slide; - width?: number; - height?: number; - originalEvent?: PointerEvent; - preventDefault?: () => void; -} - -const defaultOptions: VideoPluginOptions = { - videoAttributes: { controls: '', playsinline: '', preload: 'auto' }, - autoplay: true, - preventDragOffset: 40, -}; - -/** - * Check if slide has video content - */ -function isVideoContent(content: Content | Slide): boolean { - return content && 'data' in content && content.data && content.data.type === 'video'; -} - -class VideoContentSetup { - private options: VideoPluginOptions; - - constructor(lightbox: PhotoSwipeLightbox, options: VideoPluginOptions) { - this.options = options; - - this.initLightboxEvents(lightbox); - lightbox.on('init', () => { - if (lightbox.pswp) { - this.initPswpEvents(lightbox.pswp); - } - }); - } - - private initLightboxEvents(lightbox: PhotoSwipeLightbox): void { - lightbox.on('contentLoad', (data: unknown) => this.onContentLoad(data as EventData)); - lightbox.on('contentDestroy', (data: unknown) => this.onContentDestroy(data as { content: Content })); - lightbox.on('contentActivate', (data: unknown) => this.onContentActivate(data as { content: Content })); - lightbox.on('contentDeactivate', (data: unknown) => this.onContentDeactivate(data as { content: Content })); - lightbox.on('contentAppend', (data: unknown) => this.onContentAppend(data as EventData)); - lightbox.on('contentResize', (data: unknown) => this.onContentResize(data as EventData)); - - lightbox.addFilter('isKeepingPlaceholder', (value: unknown, ...args: unknown[]) => - this.isKeepingPlaceholder(value as boolean, args[0] as Content), - ); - lightbox.addFilter('isContentZoomable', (value: unknown, ...args: unknown[]) => - this.isContentZoomable(value as boolean, args[0] as Content), - ); - lightbox.addFilter('useContentPlaceholder', (value: unknown, ...args: unknown[]) => - this.useContentPlaceholder(value as boolean, args[0] as Content), - ); - - lightbox.addFilter('domItemData', (value: unknown, ...args: unknown[]) => { - const itemData = value as Record; - const linkEl = args[1] as HTMLAnchorElement; - - if (itemData.type === 'video' && linkEl) { - if (linkEl.dataset.pswpVideoSources) { - itemData.videoSources = JSON.parse(linkEl.dataset.pswpVideoSources); - } else if (linkEl.dataset.pswpVideoSrc) { - itemData.videoSrc = linkEl.dataset.pswpVideoSrc; - } else { - itemData.videoSrc = linkEl.href; - } - } - return itemData; - }); - } - - private initPswpEvents(pswp: PhotoSwipe): void { - pswp.on('pointerDown', (data: unknown) => { - const e = data as EventData; - const slide = pswp.currSlide as Slide | undefined; - if (slide && isVideoContent(slide) && this.options.preventDragOffset) { - const origEvent = e.originalEvent; - if (origEvent && origEvent.type === 'pointerdown') { - const videoHeight = Math.ceil(slide.height * slide.currZoomLevel); - const verticalEnding = videoHeight + slide.bounds.center.y; - const pointerYPos = origEvent.pageY - pswp.offset.y; - if (pointerYPos > verticalEnding - this.options.preventDragOffset! && pointerYPos < verticalEnding) { - e.preventDefault?.(); - } - } - } - }); - - pswp.on('appendHeavy', (data: unknown) => { - const e = data as EventData; - if (e.slide && isVideoContent(e.slide) && !e.slide.isActive) { - e.preventDefault?.(); - } - }); - - pswp.on('close', () => { - const slide = pswp.currSlide as Slide | undefined; - if (slide && isVideoContent(slide.content)) { - if (!pswp.options.showHideAnimationType || pswp.options.showHideAnimationType === 'zoom') { - pswp.options.showHideAnimationType = 'fade'; - } - this.pauseVideo(slide.content); - } - }); - } - - private onContentDestroy({ content }: { content: Content }): void { - if (isVideoContent(content) && content._videoPosterImg) { - const handleLoad = () => { - if (content._videoPosterImg) { - content._videoPosterImg.removeEventListener('error', handleError); - } - }; - const handleError = () => { - // Error handler - }; - - content._videoPosterImg.addEventListener('load', handleLoad); - content._videoPosterImg.addEventListener('error', handleError); - content._videoPosterImg = undefined; - } - } - - private onContentResize(e: EventData): void { - if (e.content && isVideoContent(e.content)) { - e.preventDefault?.(); - - const width = e.width!; - const height = e.height!; - const content = e.content; - - if (content.element) { - content.element.style.width = width + 'px'; - content.element.style.height = height + 'px'; - } - - if (content.slide && content.slide.placeholder) { - const placeholderElStyle = content.slide.placeholder.element.style; - placeholderElStyle.transform = 'none'; - placeholderElStyle.width = width + 'px'; - placeholderElStyle.height = height + 'px'; - } - } - } - - private isKeepingPlaceholder(isZoomable: boolean, content: Content): boolean { - if (isVideoContent(content)) { - return false; - } - return isZoomable; - } - - private isContentZoomable(isZoomable: boolean, content: Content): boolean { - if (isVideoContent(content)) { - return false; - } - return isZoomable; - } - - private onContentActivate({ content }: { content: Content }): void { - if (isVideoContent(content) && this.options.autoplay) { - this.playVideo(content); - } - } - - private onContentDeactivate({ content }: { content: Content }): void { - if (isVideoContent(content)) { - this.pauseVideo(content); - } - } - - private onContentAppend(e: EventData): void { - if (e.content && isVideoContent(e.content)) { - e.preventDefault?.(); - e.content.isAttached = true; - e.content.appendImage?.(); - } - } - - private onContentLoad(e: EventData): void { - const content = e.content!; - - if (!isVideoContent(content)) { - return; - } - - e.preventDefault?.(); - - if (content.element) { - return; - } - - content.state = 'loading'; - content.type = 'video'; - - content.element = document.createElement('video'); - - if (this.options.videoAttributes) { - for (const key in this.options.videoAttributes) { - content.element.setAttribute(key, this.options.videoAttributes[key] || ''); - } - } - - content.element.setAttribute('poster', content.data.msrc || ''); - - this.preloadVideoPoster(content, content.data.msrc); - - content.element.style.position = 'absolute'; - content.element.style.left = '0'; - content.element.style.top = '0'; - - if (content.data.videoSources) { - for (const source of content.data.videoSources) { - const sourceEl = document.createElement('source'); - sourceEl.src = source.src; - sourceEl.type = source.type; - content.element.append(sourceEl); - } - } else if (content.data.videoSrc) { - content.element.src = content.data.videoSrc; - } - } - - private preloadVideoPoster(content: Content, src?: string): void { - if (!content._videoPosterImg && src) { - content._videoPosterImg = new Image(); - content._videoPosterImg.src = src; - if (content._videoPosterImg.complete) { - content.onLoaded?.(); - } else { - content._videoPosterImg.addEventListener('load', () => { - content.onLoaded?.(); - }); - content._videoPosterImg.addEventListener('error', () => { - content.onLoaded?.(); - }); - } - } - } - - private playVideo(content: Content): void { - if (content.element) { - (content.element as HTMLVideoElement).play(); - } - } - - private pauseVideo(content: Content): void { - if (content.element) { - (content.element as HTMLVideoElement).pause(); - } - } - - private useContentPlaceholder(usePlaceholder: boolean, content: Content): boolean { - if (isVideoContent(content)) { - return true; - } - return usePlaceholder; - } -} - -class PhotoSwipeVideoPlugin { - constructor(lightbox: PhotoSwipeLightbox, options: VideoPluginOptions = {}) { - new VideoContentSetup(lightbox, { - ...defaultOptions, - ...options, - }); - } -} - -export default PhotoSwipeVideoPlugin; -export type { VideoPluginOptions }; -`; -} - -export function getUtilsIndex(): string { - return `import path from 'node:path'; - -/** - * 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 - * @returns The normalized path relative to the gallery root directory - */ -export const getRelativePath = (resourcePath: string) => { - const galleryConfigPath = path.resolve(process.env.GALLERY_JSON_PATH || ''); - const galleryConfigDir = path.dirname(galleryConfigPath); - - const absoluteResourcePath = path.resolve(path.join(galleryConfigDir, resourcePath)); - const baseDir = path.dirname(galleryConfigDir); - - return path.relative(baseDir, absoluteResourcePath); -}; - -/** - * 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 - */ -export const getThumbnailPath = (resourcePath: string, thumbsBaseUrl?: string, thumbnailBaseUrl?: string) => { - // If thumbnail-specific baseUrl is provided, use it and combine with the path - if (thumbnailBaseUrl) { - return \`\${thumbnailBaseUrl}/\${resourcePath}\`; - } - // Otherwise, use the gallery-level thumbsBaseUrl if provided - return thumbsBaseUrl ? \`\${thumbsBaseUrl}/\${resourcePath}\` : \`gallery/images/\${path.basename(resourcePath)}\`; -}; - -/** - * 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 - */ -export const getPhotoPath = (filename: string, mediaBaseUrl?: string, url?: string) => { - // If url is provided, always use it regardless of base URL or path - if (url) { - return url; - } - - return mediaBaseUrl ? \`\${mediaBaseUrl}/\${filename}\` : filename; -}; - -/** - * 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 - */ -export const getSubgalleryThumbnailPath = (subgalleryHeaderImagePath: string) => { - const photoBasename = path.basename(subgalleryHeaderImagePath); - const subgalleryFolderName = path.basename(path.dirname(subgalleryHeaderImagePath)); - - return path.join(subgalleryFolderName, 'gallery', 'thumbnails', photoBasename); -}; -`; -} diff --git a/themes/base/.gitignore b/themes/base/.gitignore new file mode 100644 index 0000000..489afbc --- /dev/null +++ b/themes/base/.gitignore @@ -0,0 +1,6 @@ +node_modules/ +dist/ +.astro/ +_build/ +*.log +.DS_Store diff --git a/themes/base/.prettierignore b/themes/base/.prettierignore new file mode 100644 index 0000000..6a2350b --- /dev/null +++ b/themes/base/.prettierignore @@ -0,0 +1,4 @@ +**/node_modules/* +**/dist/* +**/.astro/* +**/_build/** diff --git a/themes/base/.prettierrc.mjs b/themes/base/.prettierrc.mjs new file mode 100644 index 0000000..dfaab3f --- /dev/null +++ b/themes/base/.prettierrc.mjs @@ -0,0 +1,27 @@ +/** + * @see https://prettier.io/docs/configuration + * @type {import("prettier").Config} + */ +const config = { + semi: true, + printWidth: 125, + tabWidth: 2, + useTabs: false, + singleQuote: true, + endOfLine: 'lf', + bracketSpacing: true, + trailingComma: 'all', + quoteProps: 'as-needed', + bracketSameLine: true, + plugins: ['prettier-plugin-astro'], + overrides: [ + { + files: '*.astro', + options: { + parser: 'astro', + }, + }, + ], +}; + +export default config; diff --git a/themes/base/README.md b/themes/base/README.md new file mode 100644 index 0000000..de0d382 --- /dev/null +++ b/themes/base/README.md @@ -0,0 +1,71 @@ +# base Theme + +A custom theme for Simple Photo Gallery built with Astro. + +## Development + +`GALLERY_JSON_PATH` is required. The theme reads your `gallery.json` from this path. + +First, create a gallery once (you can reuse this during theme development): + +```bash +spg init -p -g +``` + +Then run the theme dev server with the required environment variables: + +```bash +# macOS / Linux +export GALLERY_JSON_PATH="/gallery.json" +export GALLERY_OUTPUT_DIR="" +yarn dev +``` + +```bash +# Windows (PowerShell) +$env:GALLERY_JSON_PATH="C:\path\to\gallery\gallery.json" +$env:GALLERY_OUTPUT_DIR="C:\path\to\gallery" +yarn dev +``` + +```bash +# Install dependencies +yarn install + +# Build for production +yarn build + +# Preview production build +yarn preview +``` + +## Customization + +Edit `src/pages/index.astro` to customize your theme. This is the main entry point that receives gallery data and renders your gallery. + +## Building Galleries + +To use this theme when building a gallery: + +```bash +# 1. Initialize a gallery from your images folder +spg init -p -g + +# 2. Generate thumbnails (optional but recommended) +spg thumbnails -g + +# 3. Build the gallery with your theme +spg build --theme ./themes/base -g + +# Or if published to npm +spg build --theme @your-org/theme-base -g +``` + +## Structure + +- `src/pages/index.astro` - Main gallery page +- `src/layouts/` - Layout components (MainHead, MainLayout) +- `src/components/` - Reusable components (Hero) +- `src/lib/` - Utility libraries (markdown, photoswipe-video-plugin) +- `src/utils/` - Helper functions for paths and resources +- `public/` - Static assets diff --git a/themes/base/astro.config.ts b/themes/base/astro.config.ts new file mode 100644 index 0000000..7a744f9 --- /dev/null +++ b/themes/base/astro.config.ts @@ -0,0 +1,64 @@ +import fs from 'node:fs'; +import path from 'node:path'; + +import { defineConfig } from 'astro/config'; +import relativeLinks from 'astro-relative-links'; + +import type { AstroIntegration } from 'astro'; + +// Dynamically import gallery.json from source path or fallback to local +const sourceGalleryPath = process.env.GALLERY_JSON_PATH; +if (!sourceGalleryPath) throw new Error('GALLERY_JSON_PATH environment variable is not set'); + +const outputDir = process.env.GALLERY_OUTPUT_DIR || sourceGalleryPath.replace('gallery.json', ''); + +/** + * Astro integration to prevent empty content collection files from being generated + */ +function preventEmptyContentFiles(): AstroIntegration { + return { + name: 'prevent-empty-content-files', + hooks: { + 'astro:build:done': ({ dir }) => { + const filesToRemove = ['content-assets.mjs', 'content-modules.mjs']; + for (const fileName of filesToRemove) { + const filePath = path.join(dir.pathname, fileName); + if (fs.existsSync(filePath)) { + try { + const content = fs.readFileSync(filePath, 'utf8'); + if (content.trim() === 'export default new Map();' || content.trim() === '') { + fs.unlinkSync(filePath); + } + } catch { + // Silently ignore errors + } + } + } + }, + }, + }; +} + +export default defineConfig({ + output: 'static', + outDir: outputDir + '/_build', + build: { + assets: 'assets', + assetsPrefix: 'gallery', + }, + integrations: [relativeLinks(), preventEmptyContentFiles()], + publicDir: 'public', + vite: { + define: { + 'process.env.GALLERY_JSON_PATH': JSON.stringify(sourceGalleryPath), + }, + build: { + cssCodeSplit: false, + rollupOptions: { + output: { + manualChunks: undefined, + }, + }, + }, + }, +}); diff --git a/themes/base/eslint.config.mjs b/themes/base/eslint.config.mjs new file mode 100644 index 0000000..a9e1b0e --- /dev/null +++ b/themes/base/eslint.config.mjs @@ -0,0 +1,43 @@ +import eslint from '@eslint/js'; +import eslintConfigPrettier from 'eslint-config-prettier'; +import eslintPluginAstro from 'eslint-plugin-astro'; +import globals from 'globals'; +import path from 'node:path'; +import tseslint from 'typescript-eslint'; + +const tseslintConfig = tseslint.config(eslint.configs.recommended, tseslint.configs.recommended); + +export default [ + { + ignores: ['node_modules', '.astro', '**/dist/*', '**/public/*', '**/_build/**'], + }, + ...tseslintConfig, + eslintConfigPrettier, + ...eslintPluginAstro.configs['flat/recommended'], + { + files: ['**/*.{js,mjs,cjs,ts,jsx,tsx,astro}'], + languageOptions: { + ecmaVersion: 2020, + globals: { + ...globals.browser, + ...globals.node, + }, + parserOptions: { + tsconfigRootDir: import.meta.dirname, + }, + }, + settings: { + 'import/resolver': { + alias: { + map: [['@', path.resolve(import.meta.dirname, './src')]], + extensions: ['.js', '.jsx', '.ts', '.d.ts', '.tsx', '.astro'], + }, + }, + }, + rules: { + 'no-console': ['warn', { allow: ['warn', 'error'] }], + '@typescript-eslint/no-explicit-any': ['warn'], + '@typescript-eslint/consistent-type-imports': 'warn', + }, + }, +]; diff --git a/themes/base/package.json b/themes/base/package.json new file mode 100644 index 0000000..e1f3f51 --- /dev/null +++ b/themes/base/package.json @@ -0,0 +1,42 @@ +{ + "name": "base", + "version": "1.0.0", + "description": "Custom theme for Simple Photo Gallery", + "license": "MIT", + "type": "module", + "files": ["public", "src", "astro.config.ts", "tsconfig.json"], + "scripts": { + "dev": "astro dev", + "build": "astro build", + "preview": "astro preview", + "lint": "eslint . --ext .astro,.js,.jsx,.ts,.tsx", + "lint:fix": "eslint . --ext .astro,.js,.jsx,.ts,.tsx --fix", + "format": "prettier --check './**/*.{js,jsx,ts,tsx,css,scss,md,json,astro}'", + "format:fix": "prettier --write './**/*.{js,jsx,ts,tsx,css,scss,md,json,astro}'" + }, + "dependencies": { + "astro": "^5.11.0", + "astro-relative-links": "^0.4.2", + "blurhash": "^2.0.5", + "marked": "^16.4.0", + "photoswipe": "^5.4.4" + }, + "peerDependencies": { + "@simple-photo-gallery/common": "^1.0.5" + }, + "devDependencies": { + "@eslint/eslintrc": "^3.3.1", + "@eslint/js": "^9.30.1", + "@simple-photo-gallery/common": "^1.0.5", + "@types/photoswipe": "^4.1.6", + "@typescript-eslint/eslint-plugin": "^8.35.1", + "@typescript-eslint/parser": "^8.35.1", + "eslint": "^9.30.1", + "eslint-config-prettier": "^10.1.5", + "eslint-plugin-astro": "^1.3.1", + "eslint-plugin-import": "^2.31.0", + "prettier": "^3.4.2", + "prettier-plugin-astro": "^0.14.1", + "typescript": "^5.8.3" + } +} diff --git a/themes/base/src/components/Hero.astro b/themes/base/src/components/Hero.astro new file mode 100644 index 0000000..90d583c --- /dev/null +++ b/themes/base/src/components/Hero.astro @@ -0,0 +1,260 @@ +--- +import path from 'node:path'; + +import { getPhotoPath } from '@/utils'; +import { renderMarkdown } from '@/lib/markdown'; + +interface Props { + title: string; + description?: string; + thumbsBaseUrl?: string; + headerImage?: string; + headerImageBlurHash?: string; + mediaBaseUrl?: string; +} + +const { title, description, thumbsBaseUrl, headerImage, headerImageBlurHash, mediaBaseUrl } = Astro.props; + +// Parse description as Markdown if it exists +const parsedDescription: string = description ? await renderMarkdown(description) : ''; + +// Extract basename from headerImage filename, fallback to generic name +const imgBasename = headerImage ? path.basename(headerImage, path.extname(headerImage)) : 'header'; + +// Get the base path for the thumbnails +const thumbnailBasePath = thumbsBaseUrl || 'gallery/images'; + +// Original header photo (fallback) +const headerPhotoPath = getPhotoPath(headerImage || '', mediaBaseUrl); + +const portraitWidths = [360, 480, 720, 1080] as const; +const landscapeWidths = [640, 960, 1280, 1920, 2560, 3840] as const; + +const portraitAvifSrcset = portraitWidths + .map((w) => thumbnailBasePath + '/' + imgBasename + '_portrait_' + w + '.avif ' + w + 'w') + .join(', '); +const portraitJpgSrcset = portraitWidths + .map((w) => thumbnailBasePath + '/' + imgBasename + '_portrait_' + w + '.jpg ' + w + 'w') + .join(', '); + +const landscapeAvifSrcset = landscapeWidths + .map((w) => thumbnailBasePath + '/' + imgBasename + '_landscape_' + w + '.avif ' + w + 'w') + .join(', '); +const landscapeJpgSrcset = landscapeWidths + .map((w) => thumbnailBasePath + '/' + imgBasename + '_landscape_' + w + '.jpg ' + w + 'w') + .join(', '); +--- + +{ + headerImage ? ( +
+
+ {headerImageBlurHash && } + + {/* Portrait */} + + + + {/* Landscape */} + + + + {/* Fallback */} + + +
+
+
+

{title}

+ {parsedDescription &&
} +
+
+ ) : ( +
+

{title}

+ {parsedDescription &&
} +
+ ) +} + + + + diff --git a/themes/base/src/layouts/MainHead.astro b/themes/base/src/layouts/MainHead.astro new file mode 100644 index 0000000..cf3f293 --- /dev/null +++ b/themes/base/src/layouts/MainHead.astro @@ -0,0 +1,69 @@ +--- +import type { GalleryMetadata } from '@simple-photo-gallery/common'; + +interface Props { + title: string; + description?: string; + url?: string; + thumbsBaseUrl?: string; + metadata?: GalleryMetadata; + headerImageBasename?: string; +} + +const { title, description, url, thumbsBaseUrl, metadata, headerImageBasename } = 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'; +--- + + + + + {title} + + + + {/* Basic SEO */} + + {metadata?.keywords && } + {metadata?.author && } + {metadata?.canonicalUrl || (url && )} + + {/* Open Graph */} + + + {metadata?.image && } + {metadata?.ogUrl || (url && )} + + {/* Twitter */} + + + + {metadata?.image && } + + {headerImageBasename && ( + <> + + + + )} + diff --git a/themes/base/src/layouts/MainLayout.astro b/themes/base/src/layouts/MainLayout.astro new file mode 100644 index 0000000..07365cd --- /dev/null +++ b/themes/base/src/layouts/MainLayout.astro @@ -0,0 +1,48 @@ +--- +import path from 'node:path'; + +import MainHead from '@/layouts/MainHead.astro'; + +import type { GalleryMetadata } from '@simple-photo-gallery/common'; + +interface Props { + title: string; + description?: string; + url?: string; + thumbsBaseUrl?: string; + metadata?: GalleryMetadata; + analyticsScript?: string; + headerImage?: string; +} + +const { title, description, metadata, url, thumbsBaseUrl, analyticsScript, headerImage } = Astro.props; + +// Extract basename from headerImage filename +const headerImageBasename = headerImage ? path.basename(headerImage, path.extname(headerImage)) : undefined; +--- + + + + + + + + {analyticsScript && } + + + + diff --git a/themes/base/src/lib/markdown.ts b/themes/base/src/lib/markdown.ts new file mode 100644 index 0000000..36ff431 --- /dev/null +++ b/themes/base/src/lib/markdown.ts @@ -0,0 +1,37 @@ +import { marked } from 'marked'; + +// Configure marked to only allow specific formatting options +const renderer = new marked.Renderer(); + +// Disable headings by rendering them as paragraphs +renderer.heading = ({ text }: { text: string }) => { + return '

' + text + '

\n'; +}; + +// Disable images +renderer.image = () => ''; + +// Disable HTML +renderer.html = () => ''; + +// Disable tables +renderer.table = () => ''; +renderer.tablerow = () => ''; +renderer.tablecell = () => ''; + +// Configure marked options +marked.use({ + renderer: renderer, + breaks: true, + gfm: true, +}); + +/** + * Renders markdown with limited formatting options. + * Supported: paragraphs, bold, italic, lists, code blocks, blockquotes, links + * Disabled: headings (rendered as paragraphs), images, HTML, tables + */ +export async function renderMarkdown(markdown: string): Promise { + if (!markdown) return ''; + return await marked.parse(markdown); +} diff --git a/themes/base/src/lib/photoswipe-video-plugin.ts b/themes/base/src/lib/photoswipe-video-plugin.ts new file mode 100644 index 0000000..5fdf144 --- /dev/null +++ b/themes/base/src/lib/photoswipe-video-plugin.ts @@ -0,0 +1,308 @@ +import type PhotoSwipe from 'photoswipe'; +import type PhotoSwipeLightbox from 'photoswipe/lightbox'; + +interface Slide { + content: Content; + height: number; + currZoomLevel: number; + bounds: { center: { y: number } }; + placeholder?: { element: HTMLElement }; + isActive: boolean; +} + +interface Content { + data: SlideData; + element?: HTMLVideoElement | HTMLImageElement | HTMLDivElement; + state?: string; + type?: string; + isAttached?: boolean; + onLoaded?: () => void; + appendImage?: () => void; + slide?: Slide; + _videoPosterImg?: HTMLImageElement; +} + +interface SlideData { + type?: string; + msrc?: string; + videoSrc?: string; + videoSources?: Array<{ src: string; type: string }>; +} + +interface VideoPluginOptions { + videoAttributes?: Record; + autoplay?: boolean; + preventDragOffset?: number; +} + +interface EventData { + content?: Content; + slide?: Slide; + width?: number; + height?: number; + originalEvent?: PointerEvent; + preventDefault?: () => void; +} + +const defaultOptions: VideoPluginOptions = { + videoAttributes: { controls: '', playsinline: '', preload: 'auto' }, + autoplay: true, + preventDragOffset: 40, +}; + +/** + * Check if slide has video content + */ +function isVideoContent(content: Content | Slide): boolean { + return content && 'data' in content && content.data && content.data.type === 'video'; +} + +class VideoContentSetup { + private options: VideoPluginOptions; + + constructor(lightbox: PhotoSwipeLightbox, options: VideoPluginOptions) { + this.options = options; + + this.initLightboxEvents(lightbox); + lightbox.on('init', () => { + if (lightbox.pswp) { + this.initPswpEvents(lightbox.pswp); + } + }); + } + + private initLightboxEvents(lightbox: PhotoSwipeLightbox): void { + lightbox.on('contentLoad', (data: unknown) => this.onContentLoad(data as EventData)); + lightbox.on('contentDestroy', (data: unknown) => this.onContentDestroy(data as { content: Content })); + lightbox.on('contentActivate', (data: unknown) => this.onContentActivate(data as { content: Content })); + lightbox.on('contentDeactivate', (data: unknown) => this.onContentDeactivate(data as { content: Content })); + lightbox.on('contentAppend', (data: unknown) => this.onContentAppend(data as EventData)); + lightbox.on('contentResize', (data: unknown) => this.onContentResize(data as EventData)); + + lightbox.addFilter('isKeepingPlaceholder', (value: unknown, ...args: unknown[]) => + this.isKeepingPlaceholder(value as boolean, args[0] as Content), + ); + lightbox.addFilter('isContentZoomable', (value: unknown, ...args: unknown[]) => + this.isContentZoomable(value as boolean, args[0] as Content), + ); + lightbox.addFilter('useContentPlaceholder', (value: unknown, ...args: unknown[]) => + this.useContentPlaceholder(value as boolean, args[0] as Content), + ); + + lightbox.addFilter('domItemData', (value: unknown, ...args: unknown[]) => { + const itemData = value as Record; + const linkEl = args[1] as HTMLAnchorElement; + + if (itemData.type === 'video' && linkEl) { + if (linkEl.dataset.pswpVideoSources) { + itemData.videoSources = JSON.parse(linkEl.dataset.pswpVideoSources); + } else if (linkEl.dataset.pswpVideoSrc) { + itemData.videoSrc = linkEl.dataset.pswpVideoSrc; + } else { + itemData.videoSrc = linkEl.href; + } + } + return itemData; + }); + } + + private initPswpEvents(pswp: PhotoSwipe): void { + pswp.on('pointerDown', (data: unknown) => { + const e = data as EventData; + const slide = pswp.currSlide as Slide | undefined; + if (slide && isVideoContent(slide) && this.options.preventDragOffset) { + const origEvent = e.originalEvent; + if (origEvent && origEvent.type === 'pointerdown') { + const videoHeight = Math.ceil(slide.height * slide.currZoomLevel); + const verticalEnding = videoHeight + slide.bounds.center.y; + const pointerYPos = origEvent.pageY - pswp.offset.y; + if (pointerYPos > verticalEnding - this.options.preventDragOffset! && pointerYPos < verticalEnding) { + e.preventDefault?.(); + } + } + } + }); + + pswp.on('appendHeavy', (data: unknown) => { + const e = data as EventData; + if (e.slide && isVideoContent(e.slide) && !e.slide.isActive) { + e.preventDefault?.(); + } + }); + + pswp.on('close', () => { + const slide = pswp.currSlide as Slide | undefined; + if (slide && isVideoContent(slide.content)) { + if (!pswp.options.showHideAnimationType || pswp.options.showHideAnimationType === 'zoom') { + pswp.options.showHideAnimationType = 'fade'; + } + this.pauseVideo(slide.content); + } + }); + } + + private onContentDestroy({ content }: { content: Content }): void { + if (isVideoContent(content) && content._videoPosterImg) { + const handleLoad = () => { + if (content._videoPosterImg) { + content._videoPosterImg.removeEventListener('error', handleError); + } + }; + const handleError = () => { + // Error handler + }; + + content._videoPosterImg.addEventListener('load', handleLoad); + content._videoPosterImg.addEventListener('error', handleError); + content._videoPosterImg = undefined; + } + } + + private onContentResize(e: EventData): void { + if (e.content && isVideoContent(e.content)) { + e.preventDefault?.(); + + const width = e.width!; + const height = e.height!; + const content = e.content; + + if (content.element) { + content.element.style.width = width + 'px'; + content.element.style.height = height + 'px'; + } + + if (content.slide && content.slide.placeholder) { + const placeholderElStyle = content.slide.placeholder.element.style; + placeholderElStyle.transform = 'none'; + placeholderElStyle.width = width + 'px'; + placeholderElStyle.height = height + 'px'; + } + } + } + + private isKeepingPlaceholder(isZoomable: boolean, content: Content): boolean { + if (isVideoContent(content)) { + return false; + } + return isZoomable; + } + + private isContentZoomable(isZoomable: boolean, content: Content): boolean { + if (isVideoContent(content)) { + return false; + } + return isZoomable; + } + + private onContentActivate({ content }: { content: Content }): void { + if (isVideoContent(content) && this.options.autoplay) { + this.playVideo(content); + } + } + + private onContentDeactivate({ content }: { content: Content }): void { + if (isVideoContent(content)) { + this.pauseVideo(content); + } + } + + private onContentAppend(e: EventData): void { + if (e.content && isVideoContent(e.content)) { + e.preventDefault?.(); + e.content.isAttached = true; + e.content.appendImage?.(); + } + } + + private onContentLoad(e: EventData): void { + const content = e.content!; + + if (!isVideoContent(content)) { + return; + } + + e.preventDefault?.(); + + if (content.element) { + return; + } + + content.state = 'loading'; + content.type = 'video'; + + content.element = document.createElement('video'); + + if (this.options.videoAttributes) { + for (const key in this.options.videoAttributes) { + content.element.setAttribute(key, this.options.videoAttributes[key] || ''); + } + } + + content.element.setAttribute('poster', content.data.msrc || ''); + + this.preloadVideoPoster(content, content.data.msrc); + + content.element.style.position = 'absolute'; + content.element.style.left = '0'; + content.element.style.top = '0'; + + if (content.data.videoSources) { + for (const source of content.data.videoSources) { + const sourceEl = document.createElement('source'); + sourceEl.src = source.src; + sourceEl.type = source.type; + content.element.append(sourceEl); + } + } else if (content.data.videoSrc) { + content.element.src = content.data.videoSrc; + } + } + + private preloadVideoPoster(content: Content, src?: string): void { + if (!content._videoPosterImg && src) { + content._videoPosterImg = new Image(); + content._videoPosterImg.src = src; + if (content._videoPosterImg.complete) { + content.onLoaded?.(); + } else { + content._videoPosterImg.addEventListener('load', () => { + content.onLoaded?.(); + }); + content._videoPosterImg.addEventListener('error', () => { + content.onLoaded?.(); + }); + } + } + } + + private playVideo(content: Content): void { + if (content.element) { + (content.element as HTMLVideoElement).play(); + } + } + + private pauseVideo(content: Content): void { + if (content.element) { + (content.element as HTMLVideoElement).pause(); + } + } + + private useContentPlaceholder(usePlaceholder: boolean, content: Content): boolean { + if (isVideoContent(content)) { + return true; + } + return usePlaceholder; + } +} + +class PhotoSwipeVideoPlugin { + constructor(lightbox: PhotoSwipeLightbox, options: VideoPluginOptions = {}) { + new VideoContentSetup(lightbox, { + ...defaultOptions, + ...options, + }); + } +} + +export default PhotoSwipeVideoPlugin; +export type { VideoPluginOptions }; diff --git a/themes/base/src/pages/index.astro b/themes/base/src/pages/index.astro new file mode 100644 index 0000000..0bcf99c --- /dev/null +++ b/themes/base/src/pages/index.astro @@ -0,0 +1,174 @@ +--- +import fs from 'node:fs'; + +import MainLayout from '@/layouts/MainLayout.astro'; +import Hero from '@/components/Hero.astro'; +import { getPhotoPath, getThumbnailPath } from '@/utils'; + +import type { GalleryData } from '@simple-photo-gallery/common'; + +// Read gallery.json from the path provided by the build process +const galleryJsonPath = process.env.GALLERY_JSON_PATH || './gallery.json'; +const galleryData = JSON.parse(fs.readFileSync(galleryJsonPath, 'utf8')); +const gallery = galleryData as GalleryData; + +const { title, description, sections, mediaBaseUrl, thumbsBaseUrl, headerImage, headerImageBlurHash } = gallery; +--- + + + + +
+ + {/* Render gallery sections */} + {sections.map((section) => ( +
+ {section.title &&

{section.title}

} + {section.description &&

{section.description}

} + +
+ {section.images.map((image) => { + const imagePath = getPhotoPath(image.filename, mediaBaseUrl, image.url); + const thumbnailPath = image.thumbnail + ? getThumbnailPath(image.thumbnail.path, thumbsBaseUrl, image.thumbnail.baseUrl) + : imagePath; + + const thumbnailSrcSet = image.thumbnail + ? getThumbnailPath(image.thumbnail.path, thumbsBaseUrl, image.thumbnail.baseUrl) + + ' 1x, ' + + getThumbnailPath(image.thumbnail.pathRetina, thumbsBaseUrl, image.thumbnail.baseUrl) + + ' 2x' + : undefined; + + return ( + + {image.alt + {image.alt && {image.alt}} + + ); + })} +
+
+ ))} +
+ + + + + diff --git a/themes/base/src/utils/index.ts b/themes/base/src/utils/index.ts new file mode 100644 index 0000000..157ad49 --- /dev/null +++ b/themes/base/src/utils/index.ts @@ -0,0 +1,64 @@ +import path from 'node:path'; + +/** + * 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 + * @returns The normalized path relative to the gallery root directory + */ +export const getRelativePath = (resourcePath: string) => { + const galleryConfigPath = path.resolve(process.env.GALLERY_JSON_PATH || ''); + const galleryConfigDir = path.dirname(galleryConfigPath); + + const absoluteResourcePath = path.resolve(path.join(galleryConfigDir, resourcePath)); + const baseDir = path.dirname(galleryConfigDir); + + return path.relative(baseDir, absoluteResourcePath); +}; + +/** + * 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 + */ +export const getThumbnailPath = (resourcePath: string, thumbsBaseUrl?: string, thumbnailBaseUrl?: string) => { + // If thumbnail-specific baseUrl is provided, use it and combine with the path + if (thumbnailBaseUrl) { + return `${thumbnailBaseUrl}/${resourcePath}`; + } + // Otherwise, use the gallery-level thumbsBaseUrl if provided + return thumbsBaseUrl ? `${thumbsBaseUrl}/${resourcePath}` : `gallery/images/${path.basename(resourcePath)}`; +}; + +/** + * 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 + */ +export const getPhotoPath = (filename: string, mediaBaseUrl?: string, url?: string) => { + // If url is provided, always use it regardless of base URL or path + if (url) { + return url; + } + + return mediaBaseUrl ? `${mediaBaseUrl}/${filename}` : filename; +}; + +/** + * 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 + */ +export const getSubgalleryThumbnailPath = (subgalleryHeaderImagePath: string) => { + const photoBasename = path.basename(subgalleryHeaderImagePath); + const subgalleryFolderName = path.basename(path.dirname(subgalleryHeaderImagePath)); + + return path.join(subgalleryFolderName, 'gallery', 'thumbnails', photoBasename); +}; diff --git a/themes/base/tsconfig.json b/themes/base/tsconfig.json new file mode 100644 index 0000000..990abae --- /dev/null +++ b/themes/base/tsconfig.json @@ -0,0 +1,11 @@ +{ + "extends": "astro/tsconfigs/strict", + "include": [".astro/types.d.ts", "**/*"], + "exclude": ["dist"], + "compilerOptions": { + "baseUrl": ".", + "paths": { + "@/*": ["src/*"] + } + } +} From c571e1ff3552d3b99d4a1f1fc2389cc1c59e7377 Mon Sep 17 00:00:00 2001 From: rustoma Date: Sun, 4 Jan 2026 09:48:15 +0100 Subject: [PATCH 18/55] docs: enhance theme creation documentation with detailed explanations of the base theme structure and customization options --- docs/commands/create-theme.md | 11 ++++- docs/themes.md | 19 ++++++-- themes/base/README.md | 81 +++++++++++------------------------ 3 files changed, 51 insertions(+), 60 deletions(-) diff --git a/docs/commands/create-theme.md b/docs/commands/create-theme.md index bc962a0..d97f9de 100644 --- a/docs/commands/create-theme.md +++ b/docs/commands/create-theme.md @@ -8,14 +8,23 @@ spg create-theme [options] ## How it works -The command creates a new folder containing a ready-to-edit Astro theme with: +The command creates a new theme by copying the base theme (`themes/base`) and customizing it with your theme name. The generated theme includes: - `package.json`, `astro.config.ts`, `tsconfig.json` - `src/pages/index.astro` (main entry point) - Basic layouts/components and helper utilities +- All configuration files (ESLint, Prettier, etc.) + +The command: + +1. Copies all files from `themes/base` (excluding build artifacts like `node_modules`, `.astro`, `dist`, etc.) +2. Updates `package.json` with your theme name +3. Updates `README.md` with your theme name By default, the theme is created in `./themes/`. If you run the CLI from inside a monorepo workspace, it will prefer creating themes under the **monorepo root** `./themes/`. +> **Note:** The command requires `themes/base` to exist in your workspace. This is the source template that gets copied for all new themes. + ## Options | Option | Description | Default | diff --git a/docs/themes.md b/docs/themes.md index 3acfa12..bec4db0 100644 --- a/docs/themes.md +++ b/docs/themes.md @@ -49,14 +49,22 @@ If you prefer a custom output directory: spg create-theme my-theme --path ./my-theme ``` -After that: +The `create-theme` command works by copying the base theme (`themes/base`) and customizing it with your theme name. This means: + +- All files from `themes/base` are copied (excluding build artifacts) +- The theme name is automatically updated in `package.json` and `README.md` +- You get a complete, working theme ready to customize + +After creating your theme: ```bash cd ./themes/my-theme yarn install ``` -> **Note:** The generated theme requires `GALLERY_JSON_PATH` to be set (it’s how the theme reads your `gallery.json`). When you run `spg build`, the CLI sets it automatically. When you run `astro dev` directly, you need to set it yourself (see “Theme Development” below). +> **Note:** The generated theme requires `GALLERY_JSON_PATH` to be set (it's how the theme reads your `gallery.json`). When you run `spg build`, the CLI sets it automatically. When you run `astro dev` directly, you need to set it yourself (see "Theme Development" below). + +> **Tip:** To customize the default theme structure for all new themes, edit `themes/base` directly. Any changes you make there will be reflected in themes created with `spg create-theme`. A theme is an npm package built with [Astro](https://astro.build/) that follows a specific structure and interface. @@ -313,9 +321,12 @@ yarn dev 5. **Test locally**: Use `astro dev` to preview your theme during development 6. **Follow Astro conventions**: Use Astro components, layouts, and best practices -### Example Theme Package +### Example Theme Packages + +- **`themes/base`**: The base theme template used by `spg create-theme`. This is a minimal, functional theme that serves as the starting point for all new themes. +- **`@simple-photo-gallery/theme-modern`**: A more advanced theme example. The source code is available in the `themes/modern` directory of this repository. -You can use `@simple-photo-gallery/theme-modern` as a reference implementation. The source code is available in the [themes/modern](../themes/modern) directory of this repository. +Both themes demonstrate the required structure and can be used as reference implementations. ### Using Your Theme diff --git a/themes/base/README.md b/themes/base/README.md index de0d382..e16ccad 100644 --- a/themes/base/README.md +++ b/themes/base/README.md @@ -1,71 +1,42 @@ # base Theme -A custom theme for Simple Photo Gallery built with Astro. +The base theme template for Simple Photo Gallery built with Astro. -## Development +> **⚠️ Important:** This theme is used as the **source template** for `spg create-theme`. Any changes you make to this theme will be reflected in all **new themes** created with `spg create-theme`. Existing themes created before your changes will not be affected. -`GALLERY_JSON_PATH` is required. The theme reads your `gallery.json` from this path. +## How it works -First, create a gallery once (you can reuse this during theme development): +When you run `spg create-theme `, this theme (`themes/base`) is copied to create a new theme. The command: -```bash -spg init -p -g -``` +1. Copies all files from this directory (excluding build artifacts like `node_modules`, `.astro`, `dist`, etc.) +2. Updates `package.json` with the new theme name +3. Updates `README.md` with the new theme name -Then run the theme dev server with the required environment variables: +This means: -```bash -# macOS / Linux -export GALLERY_JSON_PATH="/gallery.json" -export GALLERY_OUTPUT_DIR="" -yarn dev -``` +- **Modifying files here** → Changes will appear in themes created **after** your modifications +- **Adding new files** → New files will be included in future themes +- **Removing files** → Files won't be included in future themes +- **Existing themes** → Already created themes are not affected by changes here -```bash -# Windows (PowerShell) -$env:GALLERY_JSON_PATH="C:\path\to\gallery\gallery.json" -$env:GALLERY_OUTPUT_DIR="C:\path\to\gallery" -yarn dev -``` - -```bash -# Install dependencies -yarn install - -# Build for production -yarn build - -# Preview production build -yarn preview -``` - -## Customization - -Edit `src/pages/index.astro` to customize your theme. This is the main entry point that receives gallery data and renders your gallery. - -## Building Galleries - -To use this theme when building a gallery: - -```bash -# 1. Initialize a gallery from your images folder -spg init -p -g - -# 2. Generate thumbnails (optional but recommended) -spg thumbnails -g - -# 3. Build the gallery with your theme -spg build --theme ./themes/base -g - -# Or if published to npm -spg build --theme @your-org/theme-base -g -``` +You can customize this theme to change the default structure, dependencies, or configuration for all new themes created with `spg create-theme`. ## Structure -- `src/pages/index.astro` - Main gallery page +This theme includes the following structure that will be copied to new themes: + +- `package.json` - Package configuration (name will be updated for new themes) +- `astro.config.ts` - Astro build configuration +- `tsconfig.json` - TypeScript configuration +- `eslint.config.mjs` - ESLint configuration +- `.prettierrc.mjs` - Prettier configuration +- `.prettierignore` - Prettier ignore patterns +- `.gitignore` - Git ignore patterns +- `src/pages/index.astro` - Main gallery page entry point - `src/layouts/` - Layout components (MainHead, MainLayout) - `src/components/` - Reusable components (Hero) - `src/lib/` - Utility libraries (markdown, photoswipe-video-plugin) - `src/utils/` - Helper functions for paths and resources -- `public/` - Static assets +- `public/` - Static assets directory + +All of these files and directories will be included when creating new themes with `spg create-theme`. From 80b9904e20edb1a621216e41bb702bf2fa8e13d6 Mon Sep 17 00:00:00 2001 From: rustoma Date: Sun, 4 Jan 2026 09:55:19 +0100 Subject: [PATCH 19/55] feat: introduce bundled base theme template for theme creation with comprehensive structure, components, and configuration files --- docs/commands/create-theme.md | 6 ++-- docs/themes.md | 8 ++--- gallery/package.json | 3 +- gallery/src/modules/create-theme/index.ts | 29 ++++++++++--------- .../create-theme/templates}/base/.gitignore | 0 .../templates}/base/.prettierignore | 0 .../templates}/base/.prettierrc.mjs | 0 .../create-theme/templates}/base/README.md | 4 +-- .../templates}/base/astro.config.ts | 0 .../templates}/base/eslint.config.mjs | 0 .../create-theme/templates}/base/package.json | 0 .../templates}/base/src/components/Hero.astro | 0 .../base/src/layouts/MainHead.astro | 0 .../base/src/layouts/MainLayout.astro | 0 .../templates}/base/src/lib/markdown.ts | 0 .../base/src/lib/photoswipe-video-plugin.ts | 0 .../templates}/base/src/pages/index.astro | 0 .../templates}/base/src/utils/index.ts | 0 .../templates}/base/tsconfig.json | 0 19 files changed, 26 insertions(+), 24 deletions(-) rename {themes => gallery/src/modules/create-theme/templates}/base/.gitignore (100%) rename {themes => gallery/src/modules/create-theme/templates}/base/.prettierignore (100%) rename {themes => gallery/src/modules/create-theme/templates}/base/.prettierrc.mjs (100%) rename {themes => gallery/src/modules/create-theme/templates}/base/README.md (80%) rename {themes => gallery/src/modules/create-theme/templates}/base/astro.config.ts (100%) rename {themes => gallery/src/modules/create-theme/templates}/base/eslint.config.mjs (100%) rename {themes => gallery/src/modules/create-theme/templates}/base/package.json (100%) rename {themes => gallery/src/modules/create-theme/templates}/base/src/components/Hero.astro (100%) rename {themes => gallery/src/modules/create-theme/templates}/base/src/layouts/MainHead.astro (100%) rename {themes => gallery/src/modules/create-theme/templates}/base/src/layouts/MainLayout.astro (100%) rename {themes => gallery/src/modules/create-theme/templates}/base/src/lib/markdown.ts (100%) rename {themes => gallery/src/modules/create-theme/templates}/base/src/lib/photoswipe-video-plugin.ts (100%) rename {themes => gallery/src/modules/create-theme/templates}/base/src/pages/index.astro (100%) rename {themes => gallery/src/modules/create-theme/templates}/base/src/utils/index.ts (100%) rename {themes => gallery/src/modules/create-theme/templates}/base/tsconfig.json (100%) diff --git a/docs/commands/create-theme.md b/docs/commands/create-theme.md index d97f9de..28afb1a 100644 --- a/docs/commands/create-theme.md +++ b/docs/commands/create-theme.md @@ -8,7 +8,7 @@ spg create-theme [options] ## How it works -The command creates a new theme by copying the base theme (`themes/base`) and customizing it with your theme name. The generated theme includes: +The command creates a new theme by copying the base theme template (bundled with the package) and customizing it with your theme name. The generated theme includes: - `package.json`, `astro.config.ts`, `tsconfig.json` - `src/pages/index.astro` (main entry point) @@ -17,13 +17,13 @@ The command creates a new theme by copying the base theme (`themes/base`) and cu The command: -1. Copies all files from `themes/base` (excluding build artifacts like `node_modules`, `.astro`, `dist`, etc.) +1. Copies all files from the bundled base theme template (excluding build artifacts like `node_modules`, `.astro`, `dist`, etc.) 2. Updates `package.json` with your theme name 3. Updates `README.md` with your theme name By default, the theme is created in `./themes/`. If you run the CLI from inside a monorepo workspace, it will prefer creating themes under the **monorepo root** `./themes/`. -> **Note:** The command requires `themes/base` to exist in your workspace. This is the source template that gets copied for all new themes. +> **Note:** The base theme template is bundled with the `simple-photo-gallery` package, so `spg create-theme` works out of the box after installation. For local development, if `themes/base` exists in your workspace, it will be used instead (allowing you to test template changes). ## Options diff --git a/docs/themes.md b/docs/themes.md index bec4db0..a9ac0ab 100644 --- a/docs/themes.md +++ b/docs/themes.md @@ -49,9 +49,9 @@ If you prefer a custom output directory: spg create-theme my-theme --path ./my-theme ``` -The `create-theme` command works by copying the base theme (`themes/base`) and customizing it with your theme name. This means: +The `create-theme` command works by copying the base theme template (bundled with the package) and customizing it with your theme name. This means: -- All files from `themes/base` are copied (excluding build artifacts) +- All files from the bundled template are copied (excluding build artifacts) - The theme name is automatically updated in `package.json` and `README.md` - You get a complete, working theme ready to customize @@ -64,7 +64,7 @@ yarn install > **Note:** The generated theme requires `GALLERY_JSON_PATH` to be set (it's how the theme reads your `gallery.json`). When you run `spg build`, the CLI sets it automatically. When you run `astro dev` directly, you need to set it yourself (see "Theme Development" below). -> **Tip:** To customize the default theme structure for all new themes, edit `themes/base` directly. Any changes you make there will be reflected in themes created with `spg create-theme`. +> **Tip:** The base theme template is bundled with the `simple-photo-gallery` package. For local development, if you're working on the CLI itself and want to test template changes, you can modify `themes/base` in the repository workspace - it will be used as a fallback when present. A theme is an npm package built with [Astro](https://astro.build/) that follows a specific structure and interface. @@ -323,7 +323,7 @@ yarn dev ### Example Theme Packages -- **`themes/base`**: The base theme template used by `spg create-theme`. This is a minimal, functional theme that serves as the starting point for all new themes. +- **Base theme template**: Bundled with the `simple-photo-gallery` package and used by `spg create-theme`. This is a minimal, functional theme that serves as the starting point for all new themes. The source is in `gallery/src/modules/create-theme/templates/base` (or `themes/base` in the repository for development). - **`@simple-photo-gallery/theme-modern`**: A more advanced theme example. The source code is available in the `themes/modern` directory of this repository. Both themes demonstrate the required structure and can be used as reference implementations. diff --git a/gallery/package.json b/gallery/package.json index 1a1896f..944f0ae 100644 --- a/gallery/package.json +++ b/gallery/package.json @@ -10,7 +10,8 @@ }, "homepage": "https://simple.photo", "files": [ - "dist" + "dist", + "src/modules/create-theme/templates" ], "bin": { "simple-photo-gallery": "./dist/index.js", diff --git a/gallery/src/modules/create-theme/index.ts b/gallery/src/modules/create-theme/index.ts index ea96f96..f14dffe 100644 --- a/gallery/src/modules/create-theme/index.ts +++ b/gallery/src/modules/create-theme/index.ts @@ -121,29 +121,30 @@ async function copyDirectory(src: string, dest: string, ui: ConsolaInstance): Pr /** * Find the base theme directory path - * Tries to find themes/base relative to the workspace root or module location + * Looks for templates/base relative to this module, with fallback to workspace themes/base for development */ function findBaseThemePath(): string { - // Try to find from workspace root (monorepo root or current working directory) - const monorepoRoot = findMonorepoRoot(process.cwd()); - const workspaceRoot = monorepoRoot ?? process.cwd(); - const baseThemePath = path.join(workspaceRoot, 'themes', 'base'); + // Primary: Look for templates bundled with the package (for npm users) + // When installed from npm: dist/modules/create-theme/index.js -> src/modules/create-theme/templates/base + const moduleDir = path.dirname(fileURLToPath(import.meta.url)); + const bundledTemplatePath = path.resolve(moduleDir, '../../../src/modules/create-theme/templates/base'); - if (fs.existsSync(baseThemePath)) { - return baseThemePath; + if (fs.existsSync(bundledTemplatePath)) { + return bundledTemplatePath; } - // Fallback: try relative to the module location - // This handles the case when running from a built/compiled version - const moduleDir = path.dirname(fileURLToPath(import.meta.url)); - const relativeBaseThemePath = path.resolve(moduleDir, '../../../themes/base'); + // Fallback: Try to find from workspace root (for local development) + // This allows developers to modify themes/base and test changes + const monorepoRoot = findMonorepoRoot(process.cwd()); + const workspaceRoot = monorepoRoot ?? process.cwd(); + const workspaceBaseThemePath = path.join(workspaceRoot, 'themes', 'base'); - if (fs.existsSync(relativeBaseThemePath)) { - return relativeBaseThemePath; + if (fs.existsSync(workspaceBaseThemePath)) { + return workspaceBaseThemePath; } throw new Error( - `Base theme not found. Tried:\n - ${baseThemePath}\n - ${relativeBaseThemePath}\n\nPlease ensure themes/base exists in the workspace.`, + `Base theme template not found. Tried:\n - ${bundledTemplatePath}\n - ${workspaceBaseThemePath}\n\nPlease ensure the templates are included in the package or themes/base exists in the workspace.`, ); } diff --git a/themes/base/.gitignore b/gallery/src/modules/create-theme/templates/base/.gitignore similarity index 100% rename from themes/base/.gitignore rename to gallery/src/modules/create-theme/templates/base/.gitignore diff --git a/themes/base/.prettierignore b/gallery/src/modules/create-theme/templates/base/.prettierignore similarity index 100% rename from themes/base/.prettierignore rename to gallery/src/modules/create-theme/templates/base/.prettierignore diff --git a/themes/base/.prettierrc.mjs b/gallery/src/modules/create-theme/templates/base/.prettierrc.mjs similarity index 100% rename from themes/base/.prettierrc.mjs rename to gallery/src/modules/create-theme/templates/base/.prettierrc.mjs diff --git a/themes/base/README.md b/gallery/src/modules/create-theme/templates/base/README.md similarity index 80% rename from themes/base/README.md rename to gallery/src/modules/create-theme/templates/base/README.md index e16ccad..3d157c2 100644 --- a/themes/base/README.md +++ b/gallery/src/modules/create-theme/templates/base/README.md @@ -2,11 +2,11 @@ The base theme template for Simple Photo Gallery built with Astro. -> **⚠️ Important:** This theme is used as the **source template** for `spg create-theme`. Any changes you make to this theme will be reflected in all **new themes** created with `spg create-theme`. Existing themes created before your changes will not be affected. +> **⚠️ Important:** This theme is used as the **source template** for `spg create-theme`. This template is bundled with the `simple-photo-gallery` package, so any changes made here will be reflected in all **new themes** created with `spg create-theme` after the package is updated and published. Existing themes created before your changes will not be affected. ## How it works -When you run `spg create-theme `, this theme (`themes/base`) is copied to create a new theme. The command: +When you run `spg create-theme `, this template (bundled with the package) is copied to create a new theme. The command: 1. Copies all files from this directory (excluding build artifacts like `node_modules`, `.astro`, `dist`, etc.) 2. Updates `package.json` with the new theme name diff --git a/themes/base/astro.config.ts b/gallery/src/modules/create-theme/templates/base/astro.config.ts similarity index 100% rename from themes/base/astro.config.ts rename to gallery/src/modules/create-theme/templates/base/astro.config.ts diff --git a/themes/base/eslint.config.mjs b/gallery/src/modules/create-theme/templates/base/eslint.config.mjs similarity index 100% rename from themes/base/eslint.config.mjs rename to gallery/src/modules/create-theme/templates/base/eslint.config.mjs diff --git a/themes/base/package.json b/gallery/src/modules/create-theme/templates/base/package.json similarity index 100% rename from themes/base/package.json rename to gallery/src/modules/create-theme/templates/base/package.json diff --git a/themes/base/src/components/Hero.astro b/gallery/src/modules/create-theme/templates/base/src/components/Hero.astro similarity index 100% rename from themes/base/src/components/Hero.astro rename to gallery/src/modules/create-theme/templates/base/src/components/Hero.astro diff --git a/themes/base/src/layouts/MainHead.astro b/gallery/src/modules/create-theme/templates/base/src/layouts/MainHead.astro similarity index 100% rename from themes/base/src/layouts/MainHead.astro rename to gallery/src/modules/create-theme/templates/base/src/layouts/MainHead.astro diff --git a/themes/base/src/layouts/MainLayout.astro b/gallery/src/modules/create-theme/templates/base/src/layouts/MainLayout.astro similarity index 100% rename from themes/base/src/layouts/MainLayout.astro rename to gallery/src/modules/create-theme/templates/base/src/layouts/MainLayout.astro diff --git a/themes/base/src/lib/markdown.ts b/gallery/src/modules/create-theme/templates/base/src/lib/markdown.ts similarity index 100% rename from themes/base/src/lib/markdown.ts rename to gallery/src/modules/create-theme/templates/base/src/lib/markdown.ts diff --git a/themes/base/src/lib/photoswipe-video-plugin.ts b/gallery/src/modules/create-theme/templates/base/src/lib/photoswipe-video-plugin.ts similarity index 100% rename from themes/base/src/lib/photoswipe-video-plugin.ts rename to gallery/src/modules/create-theme/templates/base/src/lib/photoswipe-video-plugin.ts diff --git a/themes/base/src/pages/index.astro b/gallery/src/modules/create-theme/templates/base/src/pages/index.astro similarity index 100% rename from themes/base/src/pages/index.astro rename to gallery/src/modules/create-theme/templates/base/src/pages/index.astro diff --git a/themes/base/src/utils/index.ts b/gallery/src/modules/create-theme/templates/base/src/utils/index.ts similarity index 100% rename from themes/base/src/utils/index.ts rename to gallery/src/modules/create-theme/templates/base/src/utils/index.ts diff --git a/themes/base/tsconfig.json b/gallery/src/modules/create-theme/templates/base/tsconfig.json similarity index 100% rename from themes/base/tsconfig.json rename to gallery/src/modules/create-theme/templates/base/tsconfig.json From f1cf8398f5e5f6c8977a8760c1bee8a6a82ee2a4 Mon Sep 17 00:00:00 2001 From: rustoma Date: Sun, 4 Jan 2026 09:57:29 +0100 Subject: [PATCH 20/55] docs: clarify base theme template location and local development instructions in theme-related documentation --- README.md | 6 ++++++ docs/commands/create-theme.md | 2 +- docs/themes.md | 2 +- 3 files changed, 8 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 9afb381..3cf52be 100644 --- a/README.md +++ b/README.md @@ -67,22 +67,26 @@ This will: This is a monorepo using Yarn workspaces. To set up the development environment: 1. **Clone the repository** + ```bash git clone https://github.com/SimplePhotoGallery/core.git cd spg-core ``` 2. **Install dependencies** + ```bash yarn install ``` 3. **Build the `common` package** (required for TypeScript/ESLint to resolve `@simple-photo-gallery/common`) + ```bash yarn workspace @simple-photo-gallery/common build ``` 4. **Build the gallery package** (optional, for testing CLI changes) + ```bash yarn workspace simple-photo-gallery build ``` @@ -96,11 +100,13 @@ This is a monorepo using Yarn workspaces. To set up the development environment: - `common/` - Shared types and utilities (must be built first) - `gallery/` - CLI tool (`simple-photo-gallery`) + - `gallery/src/modules/create-theme/templates/base/` - Base theme template used by `spg create-theme` (bundled with the package) - `themes/modern/` - Default theme package ### Building Packages Each workspace package can be built individually: + - `yarn workspace @simple-photo-gallery/common build` - `yarn workspace simple-photo-gallery build` - `yarn workspace @simple-photo-gallery/theme-modern build` diff --git a/docs/commands/create-theme.md b/docs/commands/create-theme.md index 28afb1a..a2fd275 100644 --- a/docs/commands/create-theme.md +++ b/docs/commands/create-theme.md @@ -23,7 +23,7 @@ The command: By default, the theme is created in `./themes/`. If you run the CLI from inside a monorepo workspace, it will prefer creating themes under the **monorepo root** `./themes/`. -> **Note:** The base theme template is bundled with the `simple-photo-gallery` package, so `spg create-theme` works out of the box after installation. For local development, if `themes/base` exists in your workspace, it will be used instead (allowing you to test template changes). +> **Note:** The base theme template is bundled with the `simple-photo-gallery` package, so `spg create-theme` works out of the box after installation. The template source is located at `gallery/src/modules/create-theme/templates/base` in the repository. For local development, if `themes/base` exists in your workspace root, it will be used as a fallback (allowing you to test template changes without modifying the bundled template). ## Options diff --git a/docs/themes.md b/docs/themes.md index a9ac0ab..3a94222 100644 --- a/docs/themes.md +++ b/docs/themes.md @@ -64,7 +64,7 @@ yarn install > **Note:** The generated theme requires `GALLERY_JSON_PATH` to be set (it's how the theme reads your `gallery.json`). When you run `spg build`, the CLI sets it automatically. When you run `astro dev` directly, you need to set it yourself (see "Theme Development" below). -> **Tip:** The base theme template is bundled with the `simple-photo-gallery` package. For local development, if you're working on the CLI itself and want to test template changes, you can modify `themes/base` in the repository workspace - it will be used as a fallback when present. +> **Tip:** The base theme template is bundled with the `simple-photo-gallery` package. The source is located at `gallery/src/modules/create-theme/templates/base` in the repository. For local development, if you're working on the CLI itself and want to test template changes, you can modify the template files there. Alternatively, you can create `themes/base` in the workspace root as a fallback for testing - it will be used if present. A theme is an npm package built with [Astro](https://astro.build/) that follows a specific structure and interface. From 34c34262bc121eb3cc9c3735958993cb38df4fa8 Mon Sep 17 00:00:00 2001 From: rustoma Date: Wed, 14 Jan 2026 19:00:54 +0100 Subject: [PATCH 21/55] feat: generate README.md from template for new themes --- docs/commands/create-theme.md | 2 +- gallery/src/modules/create-theme/index.ts | 43 +++++++++++++------ .../templates/base/README_BASE.md | 25 +++++++++++ 3 files changed, 57 insertions(+), 13 deletions(-) create mode 100644 gallery/src/modules/create-theme/templates/base/README_BASE.md diff --git a/docs/commands/create-theme.md b/docs/commands/create-theme.md index a2fd275..9058cba 100644 --- a/docs/commands/create-theme.md +++ b/docs/commands/create-theme.md @@ -19,7 +19,7 @@ The command: 1. Copies all files from the bundled base theme template (excluding build artifacts like `node_modules`, `.astro`, `dist`, etc.) 2. Updates `package.json` with your theme name -3. Updates `README.md` with your theme name +3. Generates `README.md` for the new theme (from the template's `README_BASE.md`) By default, the theme is created in `./themes/`. If you run the CLI from inside a monorepo workspace, it will prefer creating themes under the **monorepo root** `./themes/`. diff --git a/gallery/src/modules/create-theme/index.ts b/gallery/src/modules/create-theme/index.ts index f14dffe..793e467 100644 --- a/gallery/src/modules/create-theme/index.ts +++ b/gallery/src/modules/create-theme/index.ts @@ -81,6 +81,13 @@ const EXCLUDE_PATTERNS = ['node_modules', '.astro', 'dist', '_build', '.git', '* * Check if a file or directory should be excluded */ function shouldExclude(name: string): boolean { + // Template README files are not meant to be copied into a newly created theme. + // - README.md: template maintainer docs (source template warning, etc.) + // - README_BASE.md: scaffold used to generate the new theme's README.md + if (name === 'README.md' || name === 'README_BASE.md') { + return true; + } + return EXCLUDE_PATTERNS.some((pattern) => { if (pattern.includes('*')) { const regexPattern = pattern.split('*').join('.*'); @@ -164,27 +171,39 @@ async function updatePackageJson(themeDir: string, themeName: string, ui: Consol } /** - * Update README.md with the new theme name + * Create README.md from README_BASE.md and fill placeholders with the new theme name + * @param baseThemePath - Base theme template directory path * @param themeDir - Theme directory path * @param themeName - New theme name * @param ui - ConsolaInstance for logging */ -async function updateReadme(themeDir: string, themeName: string, ui: ConsolaInstance): Promise { +async function createReadmeFromBase( + baseThemePath: string, + themeDir: string, + themeName: string, + ui: ConsolaInstance, +): Promise { + const readmeBasePath = path.join(baseThemePath, 'README_BASE.md'); const readmePath = path.join(themeDir, 'README.md'); - let readme = await fs.promises.readFile(readmePath, 'utf8'); - // Replace theme name references - // Replace "# base Theme" with "# {themeName} Theme" - readme = readme.replace(/^# base Theme$/m, `# ${themeName} Theme`); + if (!fs.existsSync(readmeBasePath)) { + throw new Error(`README_BASE.md not found in template: ${readmeBasePath}`); + } + + let readme = await fs.promises.readFile(readmeBasePath, 'utf8'); - // Replace "./themes/base" with "./themes/{themeName}" - readme = readme.split('./themes/base').join(`./themes/${themeName}`); + // Display name: "my-theme" -> "My Theme" + const displayName = themeName + .split('-') + .filter(Boolean) + .map((word) => word.charAt(0).toUpperCase() + word.slice(1)) + .join(' '); - // Replace "theme-base" with "theme-{themeName}" - readme = readme.split('theme-base').join(`theme-${themeName}`); + readme = readme.replace(/{THEME_NAME}/g, displayName); + readme = readme.replace(/{THEME_NAME_LOWER}/g, displayName.toLowerCase()); await fs.promises.writeFile(readmePath, readme, 'utf8'); - ui.debug(`Updated README.md with theme name: ${themeName}`); + ui.debug(`Created README.md from README_BASE.md for theme: ${themeName}`); } /** @@ -234,7 +253,7 @@ export async function createTheme(options: CreateThemeOptions, ui: ConsolaInstan // Update theme-specific files ui.debug('Updating theme-specific files...'); await updatePackageJson(themeDir, options.name, ui); - await updateReadme(themeDir, options.name, ui); + await createReadmeFromBase(baseThemePath, themeDir, options.name, ui); ui.success(`Theme created successfully at: ${themeDir}`); ui.info(`\nNext steps:`); diff --git a/gallery/src/modules/create-theme/templates/base/README_BASE.md b/gallery/src/modules/create-theme/templates/base/README_BASE.md new file mode 100644 index 0000000..0fd5512 --- /dev/null +++ b/gallery/src/modules/create-theme/templates/base/README_BASE.md @@ -0,0 +1,25 @@ +# {THEME_NAME} Theme + +This is the {THEME_NAME_LOWER} theme for Simple Photo Gallery built with Astro. + +## Getting Started + +1. Install dependencies: + + ```bash + yarn install + ``` + +2. Customize your theme in `src/pages/index.astro` + +3. Initialize a gallery (run from directory with your images): + + ```bash + spg init -p + ``` + +4. Build a gallery with your theme: + + ```bash + spg build --theme -g + ``` From 44fad4e0da07502f8d21a04ae950660d365822a7 Mon Sep 17 00:00:00 2001 From: rustoma Date: Thu, 15 Jan 2026 16:19:27 +0100 Subject: [PATCH 22/55] chore: update TypeScript configuration and improve README generation --- gallery/src/modules/create-theme/index.ts | 4 ++-- tsconfig.json | 3 ++- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/gallery/src/modules/create-theme/index.ts b/gallery/src/modules/create-theme/index.ts index 793e467..5f11e6f 100644 --- a/gallery/src/modules/create-theme/index.ts +++ b/gallery/src/modules/create-theme/index.ts @@ -199,8 +199,8 @@ async function createReadmeFromBase( .map((word) => word.charAt(0).toUpperCase() + word.slice(1)) .join(' '); - readme = readme.replace(/{THEME_NAME}/g, displayName); - readme = readme.replace(/{THEME_NAME_LOWER}/g, displayName.toLowerCase()); + readme = readme.replaceAll('{THEME_NAME}', displayName); + readme = readme.replaceAll('{THEME_NAME_LOWER}', displayName.toLowerCase()); await fs.promises.writeFile(readmePath, readme, 'utf8'); ui.debug(`Created README.md from README_BASE.md for theme: ${themeName}`); diff --git a/tsconfig.json b/tsconfig.json index 6a7dc42..e2c588d 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -1,6 +1,7 @@ { "compilerOptions": { - "target": "ES2020", + "target": "ES2021", + "lib": ["ES2021"], "module": "ESNext", "moduleResolution": "Bundler", "strict": true, From 0032c75407c6e1a0e4620ac0f8c2d61238bac672 Mon Sep 17 00:00:00 2001 From: rustoma Date: Thu, 15 Jan 2026 16:20:36 +0100 Subject: [PATCH 23/55] chore: add process import to Astro configuration and utility functions --- gallery/src/modules/create-theme/templates/base/astro.config.ts | 1 + .../src/modules/create-theme/templates/base/src/utils/index.ts | 2 ++ 2 files changed, 3 insertions(+) diff --git a/gallery/src/modules/create-theme/templates/base/astro.config.ts b/gallery/src/modules/create-theme/templates/base/astro.config.ts index 7a744f9..5e94a7a 100644 --- a/gallery/src/modules/create-theme/templates/base/astro.config.ts +++ b/gallery/src/modules/create-theme/templates/base/astro.config.ts @@ -3,6 +3,7 @@ import path from 'node:path'; import { defineConfig } from 'astro/config'; import relativeLinks from 'astro-relative-links'; +import process from 'node:process'; import type { AstroIntegration } from 'astro'; diff --git a/gallery/src/modules/create-theme/templates/base/src/utils/index.ts b/gallery/src/modules/create-theme/templates/base/src/utils/index.ts index 157ad49..6cff52f 100644 --- a/gallery/src/modules/create-theme/templates/base/src/utils/index.ts +++ b/gallery/src/modules/create-theme/templates/base/src/utils/index.ts @@ -1,5 +1,7 @@ import path from 'node:path'; +import process from 'node:process'; + /** * Normalizes resource paths to be relative to the gallery root directory. * From 0284586d1094a790c3c03429d1988f9086faa06b Mon Sep 17 00:00:00 2001 From: rustoma Date: Thu, 15 Jan 2026 16:31:10 +0100 Subject: [PATCH 24/55] chore: update TypeScript configuration and clean up imports in Astro config and utility functions --- gallery/src/modules/create-theme/templates/base/astro.config.ts | 2 +- .../src/modules/create-theme/templates/base/src/utils/index.ts | 1 - gallery/tsconfig.json | 1 + 3 files changed, 2 insertions(+), 2 deletions(-) diff --git a/gallery/src/modules/create-theme/templates/base/astro.config.ts b/gallery/src/modules/create-theme/templates/base/astro.config.ts index 5e94a7a..905516a 100644 --- a/gallery/src/modules/create-theme/templates/base/astro.config.ts +++ b/gallery/src/modules/create-theme/templates/base/astro.config.ts @@ -1,9 +1,9 @@ import fs from 'node:fs'; import path from 'node:path'; +import process from 'node:process'; import { defineConfig } from 'astro/config'; import relativeLinks from 'astro-relative-links'; -import process from 'node:process'; import type { AstroIntegration } from 'astro'; diff --git a/gallery/src/modules/create-theme/templates/base/src/utils/index.ts b/gallery/src/modules/create-theme/templates/base/src/utils/index.ts index 6cff52f..58a3f93 100644 --- a/gallery/src/modules/create-theme/templates/base/src/utils/index.ts +++ b/gallery/src/modules/create-theme/templates/base/src/utils/index.ts @@ -1,5 +1,4 @@ import path from 'node:path'; - import process from 'node:process'; /** diff --git a/gallery/tsconfig.json b/gallery/tsconfig.json index 9bac36a..68dda54 100644 --- a/gallery/tsconfig.json +++ b/gallery/tsconfig.json @@ -2,6 +2,7 @@ "extends": "../tsconfig.json", "compilerOptions": { "outDir": "./dist", + "lib": ["ES2021", "DOM"], "types": ["node", "jest"], "declaration": true, "declarationMap": true, From 942f13bab63527bbeb7e149499ab0b0ab39ddfa9 Mon Sep 17 00:00:00 2001 From: rustoma Date: Thu, 15 Jan 2026 16:35:57 +0100 Subject: [PATCH 25/55] chore: refine ESLint configuration for TypeScript and JavaScript files --- gallery/eslint.config.mjs | 69 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 68 insertions(+), 1 deletion(-) diff --git a/gallery/eslint.config.mjs b/gallery/eslint.config.mjs index aa637be..1197bda 100644 --- a/gallery/eslint.config.mjs +++ b/gallery/eslint.config.mjs @@ -28,7 +28,7 @@ const eslintConfig = [ importPlugin.flatConfigs.recommended, importPlugin.flatConfigs.typescript, { - files: ['**/*.{js,mjs,cjs,ts,jsx,tsx}'], + files: ['**/*.ts', '**/*.tsx'], languageOptions: { ecmaVersion: 2020, parserOptions: { @@ -109,6 +109,73 @@ const eslintConfig = [ 'unicorn/consistent-function-scoping': 'off', }, }, + { + files: ['**/*.{js,mjs,cjs}'], + languageOptions: { + ecmaVersion: 2020, + parserOptions: { + tsconfigRootDir: import.meta.dirname, + }, + globals: { + ...globals.jest, + ...globals.browser, + ...globals.node, + AddEventListenerOptions: 'readonly', + EventListener: 'readonly', + }, + }, + settings: { + 'import/resolver': { + node: { + paths: ['src'], + extensions: ['.js', '.jsx', '.ts', '.d.ts', '.tsx'], + }, + alias: { + map: [['@', path.resolve(import.meta.dirname, './src')]], + extensions: ['.js', '.jsx', '.ts', '.d.ts', '.tsx'], + }, + }, + }, + rules: { + 'import/no-extraneous-dependencies': 'off', + 'import/prefer-default-export': 'off', + 'import/extensions': 'off', + 'no-undef': 'error', + 'unicorn/prevent-abbreviations': 'off', + 'unicorn/no-null': 'off', + 'import/order': [ + 'warn', + { + alphabetize: { + caseInsensitive: true, + order: 'asc', + }, + groups: ['builtin', 'external', 'index', 'sibling', 'parent', 'internal', 'type'], + pathGroups: [ + { + pattern: 'react', + group: 'external', + position: 'before', + }, + ], + pathGroupsExcludedImportTypes: ['types'], + 'newlines-between': 'always', + }, + ], + 'import/no-named-as-default-member': 'off', + 'unicorn/filename-case': [ + 'error', + { + cases: { + camelCase: true, + pascalCase: true, + kebabCase: true, + }, + }, + ], + 'unicorn/consistent-function-scoping': 'off', + }, + }, ]; export default eslintConfig; From 3b02edbf03ed1701885afe4cc5aebfea1df967b0 Mon Sep 17 00:00:00 2001 From: rustoma Date: Thu, 15 Jan 2026 16:36:28 +0100 Subject: [PATCH 26/55] chore: format code for consistency and improve readability in theme templates --- .../create-theme/templates/base/package.json | 7 +- .../templates/base/src/components/Hero.astro | 72 +++++++------- .../templates/base/src/layouts/MainHead.astro | 46 ++++----- .../base/src/layouts/MainLayout.astro | 9 +- .../templates/base/src/pages/index.astro | 96 ++++++++++--------- 5 files changed, 126 insertions(+), 104 deletions(-) diff --git a/gallery/src/modules/create-theme/templates/base/package.json b/gallery/src/modules/create-theme/templates/base/package.json index e1f3f51..b499f84 100644 --- a/gallery/src/modules/create-theme/templates/base/package.json +++ b/gallery/src/modules/create-theme/templates/base/package.json @@ -4,7 +4,12 @@ "description": "Custom theme for Simple Photo Gallery", "license": "MIT", "type": "module", - "files": ["public", "src", "astro.config.ts", "tsconfig.json"], + "files": [ + "public", + "src", + "astro.config.ts", + "tsconfig.json" + ], "scripts": { "dev": "astro dev", "build": "astro build", diff --git a/gallery/src/modules/create-theme/templates/base/src/components/Hero.astro b/gallery/src/modules/create-theme/templates/base/src/components/Hero.astro index 90d583c..6c8bdf8 100644 --- a/gallery/src/modules/create-theme/templates/base/src/components/Hero.astro +++ b/gallery/src/modules/create-theme/templates/base/src/components/Hero.astro @@ -47,43 +47,43 @@ const landscapeJpgSrcset = landscapeWidths { headerImage ? ( -
-
- {headerImageBlurHash && } - - {/* Portrait */} - - - - {/* Landscape */} - - - - {/* Fallback */} - - -
-
-
-

{title}

- {parsedDescription &&
} -
-
+
+
+ {headerImageBlurHash && } + + {/* Portrait */} + + + + {/* Landscape */} + + + + {/* Fallback */} + + +
+
+
+

{title}

+ {parsedDescription &&
} +
+
) : ( -
-

{title}

- {parsedDescription &&
} -
+
+

{title}

+ {parsedDescription &&
} +
) } diff --git a/gallery/src/modules/create-theme/templates/base/src/layouts/MainHead.astro b/gallery/src/modules/create-theme/templates/base/src/layouts/MainHead.astro index cf3f293..bf186d4 100644 --- a/gallery/src/modules/create-theme/templates/base/src/layouts/MainHead.astro +++ b/gallery/src/modules/create-theme/templates/base/src/layouts/MainHead.astro @@ -44,26 +44,28 @@ const thumbnailBasePath = thumbsBaseUrl || 'gallery/images'; {metadata?.image && } - {headerImageBasename && ( - <> - - - - )} + { + headerImageBasename && ( + <> + + + + ) + } diff --git a/gallery/src/modules/create-theme/templates/base/src/layouts/MainLayout.astro b/gallery/src/modules/create-theme/templates/base/src/layouts/MainLayout.astro index 07365cd..4ccfb34 100644 --- a/gallery/src/modules/create-theme/templates/base/src/layouts/MainLayout.astro +++ b/gallery/src/modules/create-theme/templates/base/src/layouts/MainLayout.astro @@ -23,7 +23,14 @@ const headerImageBasename = headerImage ? path.basename(headerImage, path.extnam - + diff --git a/gallery/src/modules/create-theme/templates/base/src/pages/index.astro b/gallery/src/modules/create-theme/templates/base/src/pages/index.astro index 0bcf99c..dafd639 100644 --- a/gallery/src/modules/create-theme/templates/base/src/pages/index.astro +++ b/gallery/src/modules/create-theme/templates/base/src/pages/index.astro @@ -15,7 +15,14 @@ const gallery = galleryData as GalleryData; const { title, description, sections, mediaBaseUrl, thumbsBaseUrl, headerImage, headerImageBlurHash } = gallery; --- - +
- {/* Render gallery sections */} - {sections.map((section) => ( -
- {section.title &&

{section.title}

} - {section.description &&

{section.description}

} - -
- {section.images.map((image) => { - const imagePath = getPhotoPath(image.filename, mediaBaseUrl, image.url); - const thumbnailPath = image.thumbnail - ? getThumbnailPath(image.thumbnail.path, thumbsBaseUrl, image.thumbnail.baseUrl) - : imagePath; - - const thumbnailSrcSet = image.thumbnail - ? getThumbnailPath(image.thumbnail.path, thumbsBaseUrl, image.thumbnail.baseUrl) + - ' 1x, ' + - getThumbnailPath(image.thumbnail.pathRetina, thumbsBaseUrl, image.thumbnail.baseUrl) + - ' 2x' - : undefined; - - return ( - - {image.alt - {image.alt && {image.alt}} - - ); - })} -
-
- ))} + { + sections.map((section) => ( +
+ {section.title &&

{section.title}

} + {section.description &&

{section.description}

} + +
+ {section.images.map((image) => { + const imagePath = getPhotoPath(image.filename, mediaBaseUrl, image.url); + const thumbnailPath = image.thumbnail + ? getThumbnailPath(image.thumbnail.path, thumbsBaseUrl, image.thumbnail.baseUrl) + : imagePath; + + const thumbnailSrcSet = image.thumbnail + ? getThumbnailPath(image.thumbnail.path, thumbsBaseUrl, image.thumbnail.baseUrl) + + ' 1x, ' + + getThumbnailPath(image.thumbnail.pathRetina, thumbsBaseUrl, image.thumbnail.baseUrl) + + ' 2x' + : undefined; + + return ( + + {image.alt + {image.alt && {image.alt}} + + ); + })} +
+
+ )) + }
From dddcd865a4ab9bf80389608445c1d8da3dca909f Mon Sep 17 00:00:00 2001 From: rustoma Date: Thu, 15 Jan 2026 16:37:03 +0100 Subject: [PATCH 27/55] chore: update ESLint configuration by removing duplicate import and ensuring consistent path handling --- .../src/modules/create-theme/templates/base/eslint.config.mjs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/gallery/src/modules/create-theme/templates/base/eslint.config.mjs b/gallery/src/modules/create-theme/templates/base/eslint.config.mjs index a9e1b0e..bf45a25 100644 --- a/gallery/src/modules/create-theme/templates/base/eslint.config.mjs +++ b/gallery/src/modules/create-theme/templates/base/eslint.config.mjs @@ -1,8 +1,9 @@ +import path from 'node:path'; + import eslint from '@eslint/js'; import eslintConfigPrettier from 'eslint-config-prettier'; import eslintPluginAstro from 'eslint-plugin-astro'; import globals from 'globals'; -import path from 'node:path'; import tseslint from 'typescript-eslint'; const tseslintConfig = tseslint.config(eslint.configs.recommended, tseslint.configs.recommended); From 229c54bcd75b732e4343494bd902f3df290e688e Mon Sep 17 00:00:00 2001 From: Vladimir Haltakov Date: Sun, 18 Jan 2026 23:10:41 +0100 Subject: [PATCH 28/55] fix: docs table layout --- docs/commands/build.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/commands/build.md b/docs/commands/build.md index 72d7416..efcf176 100644 --- a/docs/commands/build.md +++ b/docs/commands/build.md @@ -14,18 +14,18 @@ If you have created the gallery in a different folder from the photos folder, th ## Options -| Option | Description | Default | -| ----------------------------- | ------------------------------------------- | -------------------------------- | ------------------------------------ | -| `-g, --gallery ` | Path to gallery directory | Current directory | -| `-r, --recursive` | Build all galleries | `false` | -| `-b, --base-url ` | Base URL for external hosting | None | -| `-t, --thumbs-base-url ` | Base URL for external hosting of thumbnails | None | -| `--theme ` | Theme package name or local path | `@simple-photo-gallery/theme-modern` | -| `--no-scan` | Do not scan for new photos | `true` | -| `--no-thumbnails` | Skip creating thumbnails | `true` | -| `-v, --verbose` | Show detailed output | | -| `-q, --quiet` | Only show warnings/errors | | -| `-h, --help` | Show command help | | +| Option | Description | Default | +| ----------------------------- | ------------------------------------------- | ------------------------------------ | +| `-g, --gallery ` | Path to gallery directory | Current directory | +| `-r, --recursive` | Build all galleries | `false` | +| `-b, --base-url ` | Base URL for external hosting | None | +| `-t, --thumbs-base-url ` | Base URL for external hosting of thumbnails | None | +| `--theme ` | Theme package name | `@simple-photo-gallery/theme-modern` | +| `--no-scan` | Do not scan for new photos | `true` | +| `--no-thumbnails` | Skip creating thumbnails | `true` | +| `-v, --verbose` | Show detailed output | | +| `-q, --quiet` | Only show warnings/errors | | +| `-h, --help` | Show command help | | ## Examples From 09f3583af45cdb4099d4be8282da9d7e96d909a6 Mon Sep 17 00:00:00 2001 From: rustoma Date: Tue, 20 Jan 2026 19:46:45 +0100 Subject: [PATCH 29/55] chore: enhance theme structure by adding client and theme modules, updating dependencies, and refining TypeScript configurations --- common/package.json | 22 + .../src/client.ts | 199 +++++++- common/src/theme.ts | 470 ++++++++++++++++++ common/tsconfig.json | 3 +- common/tsup.config.ts | 57 ++- .../templates/base/astro.config.ts | 31 +- .../create-theme/templates/base/package.json | 1 - .../templates/base/src/components/Hero.astro | 128 +---- .../templates/base/src/lib/markdown.ts | 37 -- .../base/src/lib/photoswipe-video-plugin.ts | 308 ------------ .../templates/base/src/pages/index.astro | 94 ++-- .../templates/base/src/utils/index.ts | 65 --- themes/modern/astro.config.ts | 36 +- themes/modern/package.json | 1 - .../gallery-section/GallerySection.astro | 22 +- .../GallerySectionHeader.astro | 15 +- .../gallery-section/GallerySectionItem.astro | 30 +- .../base-theme/components/hero/Hero.astro | 138 +---- .../components/lightbox/PhotoSwipe.astro | 2 +- .../sub-galleries/SubGalleries.astro | 17 +- .../themes/base-theme/layouts/MainHead.astro | 2 +- .../themes/base-theme/pages/index.astro | 89 +--- .../features/themes/base-theme/utils/index.ts | 107 ---- themes/modern/src/lib/markdown.ts | 37 -- yarn.lock | 16 +- 25 files changed, 873 insertions(+), 1054 deletions(-) rename themes/modern/src/lib/photoswipe-video-plugin.ts => common/src/client.ts (60%) create mode 100644 common/src/theme.ts delete mode 100644 gallery/src/modules/create-theme/templates/base/src/lib/markdown.ts delete mode 100644 gallery/src/modules/create-theme/templates/base/src/lib/photoswipe-video-plugin.ts delete mode 100644 gallery/src/modules/create-theme/templates/base/src/utils/index.ts delete mode 100644 themes/modern/src/features/themes/base-theme/utils/index.ts delete mode 100644 themes/modern/src/lib/markdown.ts diff --git a/common/package.json b/common/package.json index 0ddd323..cb69872 100644 --- a/common/package.json +++ b/common/package.json @@ -16,6 +16,14 @@ "types": "./dist/gallery.d.ts", "import": "./dist/gallery.js", "require": "./dist/gallery.cjs" + }, + "./theme": { + "types": "./dist/theme.d.ts", + "import": "./dist/theme.js" + }, + "./client": { + "types": "./dist/client.d.ts", + "import": "./dist/client.js" } }, "files": [ @@ -33,12 +41,26 @@ "prepublish": "yarn build" }, "dependencies": { + "marked": "^16.0.0", "zod": "^4.0.14" }, + "peerDependencies": { + "blurhash": "^2.0.5", + "photoswipe": "^5.4.4" + }, + "peerDependenciesMeta": { + "blurhash": { + "optional": true + }, + "photoswipe": { + "optional": true + } + }, "devDependencies": { "@eslint/eslintrc": "^3.3.1", "@eslint/js": "^9.30.1", "@types/node": "^24.0.10", + "@types/photoswipe": "^4.1.6", "@typescript-eslint/eslint-plugin": "^8.38.0", "@typescript-eslint/parser": "^8.38.0", "eslint": "^9.30.1", diff --git a/themes/modern/src/lib/photoswipe-video-plugin.ts b/common/src/client.ts similarity index 60% rename from themes/modern/src/lib/photoswipe-video-plugin.ts rename to common/src/client.ts index b9721b3..9d4ea9b 100644 --- a/themes/modern/src/lib/photoswipe-video-plugin.ts +++ b/common/src/client.ts @@ -1,6 +1,166 @@ +/** + * Client-side utilities for Simple Photo Gallery themes. + * This module contains browser-only code and should only be imported in client contexts. + */ + +import { decode } from 'blurhash'; + import type PhotoSwipe from 'photoswipe'; import type PhotoSwipeLightbox from 'photoswipe/lightbox'; +// ============================================================================ +// Blurhash Utilities +// ============================================================================ + +/** + * Decode a single blurhash and draw it to a canvas element. + * + * @param canvas - The canvas element with a data-blur-hash attribute + * @param width - The width to decode at (default: 32) + * @param height - The height to decode at (default: 32) + */ +export function decodeBlurhashToCanvas( + canvas: HTMLCanvasElement, + width: number = 32, + height: number = 32, +): void { + const blurHashValue = canvas.dataset.blurHash; + if (!blurHashValue) return; + + const pixels = decode(blurHashValue, width, height); + const ctx = canvas.getContext('2d'); + if (pixels && ctx) { + const imageData = new ImageData(new Uint8ClampedArray(pixels), width, height); + ctx.putImageData(imageData, 0, 0); + } +} + +/** + * Decode and render all blurhash canvases on the page. + * Finds all canvas elements with data-blur-hash attribute and draws the decoded image. + * + * @param selector - CSS selector for canvas elements (default: 'canvas[data-blur-hash]') + * @param width - The width to decode at (default: 32) + * @param height - The height to decode at (default: 32) + */ +export function decodeAllBlurhashes( + selector: string = 'canvas[data-blur-hash]', + width: number = 32, + height: number = 32, +): void { + const canvases = document.querySelectorAll(selector); + for (const canvas of canvases) { + decodeBlurhashToCanvas(canvas, width, height); + } +} + +// ============================================================================ +// Hero Image Fallback +// ============================================================================ + +/** Options for the hero image fallback behavior */ +export interface HeroImageFallbackOptions { + /** CSS selector for the picture element (default: '#hero-bg-picture') */ + pictureSelector?: string; + /** CSS selector for the img element within picture (default: 'img.hero__bg-img') */ + imgSelector?: string; + /** CSS selector for the blurhash canvas element (default: 'canvas[data-blur-hash]') */ + canvasSelector?: string; +} + +/** + * Initialize hero image fallback behavior. + * Handles: + * - Hiding blurhash canvas when image loads successfully + * - Removing source elements and retrying with fallback src on error + * - Keeping blurhash visible if final fallback also fails + * + * @param options - Configuration options for selectors + * + * @example + * ```typescript + * import { initHeroImageFallback } from '@simple-photo-gallery/common/client'; + * + * // Use default selectors + * initHeroImageFallback(); + * + * // Or with custom selectors + * initHeroImageFallback({ + * pictureSelector: '#my-hero-picture', + * imgSelector: 'img.my-hero-img', + * canvasSelector: 'canvas.my-blurhash', + * }); + * ``` + */ +export function initHeroImageFallback(options: HeroImageFallbackOptions = {}): void { + const { + pictureSelector = '#hero-bg-picture', + imgSelector = 'img.hero__bg-img', + canvasSelector = 'canvas[data-blur-hash]', + } = options; + + const picture = document.querySelector(pictureSelector); + const img = picture?.querySelector(imgSelector); + const canvas = document.querySelector(canvasSelector); + + if (!img) return; + + const fallbackSrc = img.getAttribute('src') || ''; + let didFallback = false; + + const hideBlurhash = () => { + if (canvas) { + canvas.style.display = 'none'; + } + }; + + const doFallback = () => { + if (didFallback) return; + didFallback = true; + + if (picture) { + // Remove all elements so the browser does not retry them + for (const sourceEl of picture.querySelectorAll('source')) { + sourceEl.remove(); + } + } + + // Force reload using the src as the final fallback + const current = img.getAttribute('src') || ''; + img.setAttribute('src', ''); + img.setAttribute('src', fallbackSrc || current); + + // If fallback also fails, keep blurhash visible + img.addEventListener( + 'error', + () => { + // Final fallback failed, blurhash stays visible + }, + { once: true }, + ); + + // If fallback succeeds, hide blurhash + img.addEventListener('load', hideBlurhash, { once: true }); + }; + + // Check if image already loaded or failed before script runs + if (img.complete) { + if (img.naturalWidth === 0) { + doFallback(); + } else { + hideBlurhash(); + } + } else { + img.addEventListener('load', hideBlurhash, { once: true }); + } + + img.addEventListener('error', doFallback, { once: true }); +} + +// ============================================================================ +// PhotoSwipe Video Plugin Types +// ============================================================================ + interface Slide { content: Content; height: number; @@ -29,9 +189,13 @@ interface SlideData { videoSources?: Array<{ src: string; type: string }>; } -interface VideoPluginOptions { +/** Options for the PhotoSwipe video plugin */ +export interface VideoPluginOptions { + /** HTML attributes to apply to video elements */ videoAttributes?: Record; + /** Whether to autoplay videos when they become active */ autoplay?: boolean; + /** Pixels from bottom of video where drag is prevented (for video controls) */ preventDragOffset?: number; } @@ -44,6 +208,10 @@ interface EventData { preventDefault?: () => void; } +// ============================================================================ +// PhotoSwipe Video Plugin Implementation +// ============================================================================ + const defaultOptions: VideoPluginOptions = { videoAttributes: { controls: '', playsinline: '', preload: 'auto' }, autoplay: true, @@ -262,9 +430,6 @@ class VideoContentSetup { content.element.append(sourceEl); } } else if (content.data.videoSrc) { - // Force video preload - // https://muffinman.io/blog/hack-for-ios-safari-to-display-html-video-thumbnail/ - // this.element.src = this.data.videoSrc + '#t=0.001'; content.element.src = content.data.videoSrc; } } @@ -306,7 +471,28 @@ class VideoContentSetup { } } -class PhotoSwipeVideoPlugin { +/** + * PhotoSwipe plugin that adds video support to the lightbox. + * Videos are automatically detected by the `data-pswp-type="video"` attribute + * on gallery links. + * + * @example + * ```typescript + * import PhotoSwipe from 'photoswipe'; + * import PhotoSwipeLightbox from 'photoswipe/lightbox'; + * import { PhotoSwipeVideoPlugin } from '@simple-photo-gallery/common/client'; + * + * const lightbox = new PhotoSwipeLightbox({ + * gallery: '.gallery', + * children: 'a', + * pswpModule: PhotoSwipe, + * }); + * + * new PhotoSwipeVideoPlugin(lightbox); + * lightbox.init(); + * ``` + */ +export class PhotoSwipeVideoPlugin { constructor(lightbox: PhotoSwipeLightbox, options: VideoPluginOptions = {}) { new VideoContentSetup(lightbox, { ...defaultOptions, @@ -314,6 +500,3 @@ class PhotoSwipeVideoPlugin { }); } } - -export default PhotoSwipeVideoPlugin; -export type { VideoPluginOptions }; diff --git a/common/src/theme.ts b/common/src/theme.ts new file mode 100644 index 0000000..f4c5374 --- /dev/null +++ b/common/src/theme.ts @@ -0,0 +1,470 @@ +import fs from 'node:fs'; +import path from 'node:path'; +import process from 'node:process'; + +import { marked } from 'marked'; + +import type { + GalleryData, + GalleryMetadata, + GallerySection, + HeaderImageVariants, + MediaFile, + SubGallery, +} from './gallery'; + +// ============================================================================ +// Types +// ============================================================================ + +/** Resolved hero data with all paths computed and markdown parsed */ +export 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 */ +export 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 */ +export interface ResolvedSection { + title?: string; + description?: string; + parsedDescription: string; + images: ResolvedImage[]; +} + +/** Resolved sub-gallery with computed thumbnail path */ +export interface ResolvedSubGallery { + title: string; + headerImage: string; + path: string; + thumbnailPath: string; +} + +/** Fully resolved gallery data ready for rendering */ +export interface ResolvedGalleryData { + title: string; + url?: string; + metadata: GalleryMetadata; + analyticsScript?: string; + ctaBanner?: boolean; + hero: ResolvedHero; + sections: ResolvedSection[]; + subGalleries?: { + title: string; + galleries: ResolvedSubGallery[]; + }; + // Pass through base URLs for components that need them + mediaBaseUrl?: string; + thumbsBaseUrl?: string; +} + +// ============================================================================ +// Constants +// ============================================================================ + +/** 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; + +// ============================================================================ +// Markdown Rendering +// ============================================================================ + +// Configure marked to only allow specific formatting options +const renderer = new marked.Renderer(); + +// Disable headings by rendering them as paragraphs +renderer.heading = ({ text }: { text: string }) => { + return '

' + text + '

\n'; +}; + +// Disable images +renderer.image = () => ''; + +// Disable HTML +renderer.html = () => ''; + +// Disable tables +renderer.table = () => ''; +renderer.tablerow = () => ''; +renderer.tablecell = () => ''; + +// Configure marked options +marked.use({ + renderer: renderer, + breaks: true, + gfm: true, +}); + +/** + * Renders markdown with limited formatting options. + * Supported: paragraphs, bold, italic, lists, code blocks, blockquotes, links + * Disabled: headings (rendered as paragraphs), images, HTML, tables + */ +export async function renderMarkdown(markdown: string): Promise { + if (!markdown) return ''; + return await marked.parse(markdown); +} + +// ============================================================================ +// Path Utilities +// ============================================================================ + +/** + * 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 + * @returns The normalized path relative to the gallery root directory + */ +export function getRelativePath(resourcePath: string): string { + const galleryConfigPath = path.resolve(process.env.GALLERY_JSON_PATH || ''); + const galleryConfigDir = path.dirname(galleryConfigPath); + + const absoluteResourcePath = path.resolve(path.join(galleryConfigDir, resourcePath)); + const baseDir = path.dirname(galleryConfigDir); + + return path.relative(baseDir, absoluteResourcePath); +} + +/** + * 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 + */ +export function getThumbnailPath( + resourcePath: string, + thumbsBaseUrl?: string, + thumbnailBaseUrl?: string, +): string { + // If thumbnail-specific baseUrl is provided, use it and combine with the path + if (thumbnailBaseUrl) { + return `${thumbnailBaseUrl}/${resourcePath}`; + } + // Otherwise, use the gallery-level thumbsBaseUrl if provided + return thumbsBaseUrl ? `${thumbsBaseUrl}/${resourcePath}` : `gallery/images/${path.basename(resourcePath)}`; +} + +/** + * 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 + */ +export function getPhotoPath(filename: string, mediaBaseUrl?: string, url?: string): string { + // If url is provided, always use it regardless of base URL or path + if (url) { + return url; + } + + return mediaBaseUrl ? `${mediaBaseUrl}/${filename}` : filename; +} + +/** + * 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 + */ +export function getSubgalleryThumbnailPath(subgalleryHeaderImagePath: string): string { + const photoBasename = path.basename(subgalleryHeaderImagePath); + const subgalleryFolderName = path.basename(path.dirname(subgalleryHeaderImagePath)); + + return path.join(subgalleryFolderName, 'gallery', 'thumbnails', photoBasename); +} + +/** + * 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 function buildHeroSrcset( + variants: Record | 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(', '); +} + +// ============================================================================ +// Gallery Loading +// ============================================================================ + +/** + * Load gallery data from the GALLERY_JSON_PATH environment variable. + * + * @returns The parsed gallery data + * @throws Error if GALLERY_JSON_PATH is not set or file cannot be read + */ +export function loadGalleryData(): GalleryData { + const galleryJsonPath = process.env.GALLERY_JSON_PATH || './gallery.json'; + const galleryData = JSON.parse(fs.readFileSync(galleryJsonPath, 'utf8')); + return galleryData as GalleryData; +} + +// ============================================================================ +// Data Resolution +// ============================================================================ + +/** + * Resolve a single image with all paths computed. + */ +function resolveImage(image: MediaFile, mediaBaseUrl?: string, thumbsBaseUrl?: string): ResolvedImage { + const imagePath = getPhotoPath(image.filename, mediaBaseUrl, image.url); + const thumbnailPath = image.thumbnail + ? getThumbnailPath(image.thumbnail.path, thumbsBaseUrl, image.thumbnail.baseUrl) + : imagePath; + + const thumbnailSrcSet = image.thumbnail + ? getThumbnailPath(image.thumbnail.path, thumbsBaseUrl, image.thumbnail.baseUrl) + + ' 1x, ' + + getThumbnailPath(image.thumbnail.pathRetina, thumbsBaseUrl, image.thumbnail.baseUrl) + + ' 2x' + : undefined; + + return { + type: image.type, + filename: image.filename, + alt: image.alt, + width: image.width, + height: image.height, + imagePath, + thumbnailPath, + thumbnailSrcSet, + thumbnailWidth: image.thumbnail?.width, + thumbnailHeight: image.thumbnail?.height, + blurHash: image.thumbnail?.blurHash, + }; +} + +/** + * Resolve a section with parsed markdown and resolved image paths. + */ +async function resolveSection( + section: GallerySection, + mediaBaseUrl?: string, + thumbsBaseUrl?: string, +): Promise { + const parsedDescription = section.description ? await renderMarkdown(section.description) : ''; + + return { + title: section.title, + description: section.description, + parsedDescription, + images: section.images.map((img) => resolveImage(img, mediaBaseUrl, thumbsBaseUrl)), + }; +} + +/** + * Resolve a sub-gallery with computed thumbnail path. + */ +function resolveSubGallery(subGallery: SubGallery): ResolvedSubGallery { + return { + title: subGallery.title, + headerImage: subGallery.headerImage, + path: subGallery.path, + thumbnailPath: getSubgalleryThumbnailPath(subGallery.headerImage), + }; +} + +/** + * Resolve hero data with all paths computed and srcsets built. + */ +async function resolveHero(gallery: GalleryData): Promise { + const { title, description, headerImage, headerImageBlurHash, headerImageVariants, mediaBaseUrl, thumbsBaseUrl } = + gallery; + + const parsedDescription = description ? await renderMarkdown(description) : ''; + const imgBasename = headerImage ? path.basename(headerImage, path.extname(headerImage)) : 'header'; + const thumbnailBasePath = thumbsBaseUrl || 'gallery/images'; + const headerPhotoPath = getPhotoPath(headerImage || '', mediaBaseUrl); + + // Determine which sources to show based on headerImageVariants + // If headerImageVariants is not set, use all generated paths (default behavior) + const useDefaultPaths = !headerImageVariants; + + const srcsets = { + portraitAvif: buildHeroSrcset( + headerImageVariants?.portrait?.avif, + PORTRAIT_SIZES, + thumbnailBasePath, + imgBasename, + 'portrait', + 'avif', + useDefaultPaths, + ), + portraitJpg: buildHeroSrcset( + headerImageVariants?.portrait?.jpg, + PORTRAIT_SIZES, + thumbnailBasePath, + imgBasename, + 'portrait', + 'jpg', + useDefaultPaths, + ), + landscapeAvif: buildHeroSrcset( + headerImageVariants?.landscape?.avif, + LANDSCAPE_SIZES, + thumbnailBasePath, + imgBasename, + 'landscape', + 'avif', + useDefaultPaths, + ), + landscapeJpg: buildHeroSrcset( + headerImageVariants?.landscape?.jpg, + LANDSCAPE_SIZES, + thumbnailBasePath, + imgBasename, + 'landscape', + 'jpg', + useDefaultPaths, + ), + }; + + return { + title, + description, + parsedDescription, + headerImage, + headerPhotoPath, + headerImageBlurHash, + headerImageVariants, + thumbnailBasePath, + imgBasename, + srcsets, + }; +} + +/** + * 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() + * @returns Fully resolved gallery data ready for rendering + */ +export async function resolveGalleryData(gallery: GalleryData): Promise { + const { mediaBaseUrl, thumbsBaseUrl, subGalleries } = gallery; + + const hero = await resolveHero(gallery); + const sections = await Promise.all( + gallery.sections.map((section) => resolveSection(section, mediaBaseUrl, thumbsBaseUrl)), + ); + + const resolvedSubGalleries = subGalleries?.galleries?.length + ? { + title: subGalleries.title, + galleries: subGalleries.galleries.map((sg) => resolveSubGallery(sg)), + } + : undefined; + + return { + title: gallery.title, + url: gallery.url, + metadata: gallery.metadata, + analyticsScript: gallery.analyticsScript, + ctaBanner: gallery.ctaBanner, + hero, + sections, + subGalleries: resolvedSubGalleries, + mediaBaseUrl, + thumbsBaseUrl, + }; +} + +// ============================================================================ +// Astro Integration +// ============================================================================ + +/** 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. + */ +export function preventEmptyContentFiles(): AstroIntegration { + return { + name: 'prevent-empty-content-files', + hooks: { + 'astro:build:done': ({ dir }) => { + const filesToRemove = ['content-assets.mjs', 'content-modules.mjs']; + for (const fileName of filesToRemove) { + const filePath = path.join(dir.pathname, fileName); + if (fs.existsSync(filePath)) { + try { + const content = fs.readFileSync(filePath, 'utf8'); + if (content.trim() === 'export default new Map();' || content.trim() === '') { + fs.unlinkSync(filePath); + } + } catch { + // Silently ignore errors + } + } + } + }, + }, + }; +} diff --git a/common/tsconfig.json b/common/tsconfig.json index 44b1402..d370185 100644 --- a/common/tsconfig.json +++ b/common/tsconfig.json @@ -1,7 +1,8 @@ { "extends": "../tsconfig.json", "compilerOptions": { - "noEmit": true + "noEmit": true, + "lib": ["ES2021", "DOM", "DOM.Iterable"] }, "include": ["src/**/*.ts", "tsup.config.ts"] } diff --git a/common/tsup.config.ts b/common/tsup.config.ts index 8f2c0c3..adac965 100644 --- a/common/tsup.config.ts +++ b/common/tsup.config.ts @@ -1,15 +1,46 @@ import { defineConfig } from 'tsup'; -export default defineConfig({ - entry: ['src/gallery.ts'], - format: ['esm', 'cjs'], - dts: true, - splitting: false, - sourcemap: true, - clean: true, - minify: false, - target: 'node20', - outDir: 'dist', - treeshake: true, - external: ['zod'], -}); +export default defineConfig([ + // Main entry point: types + schemas (no heavy deps) + { + entry: ['src/gallery.ts'], + format: ['esm', 'cjs'], + dts: true, + splitting: false, + sourcemap: true, + clean: true, + minify: false, + target: 'node20', + outDir: 'dist', + treeshake: true, + external: ['zod'], + }, + // Theme entry point: server-side utilities + { + entry: ['src/theme.ts'], + format: ['esm'], + dts: true, + splitting: false, + sourcemap: true, + clean: false, + minify: false, + target: 'node20', + outDir: 'dist', + treeshake: true, + external: ['zod', 'marked'], + }, + // Client entry point: browser-side utilities (PhotoSwipe plugin, blurhash) + { + entry: ['src/client.ts'], + format: ['esm'], + dts: true, + splitting: false, + sourcemap: true, + clean: false, + minify: false, + target: 'es2020', + outDir: 'dist', + treeshake: true, + external: ['photoswipe', 'photoswipe/lightbox', 'blurhash'], + }, +]); diff --git a/gallery/src/modules/create-theme/templates/base/astro.config.ts b/gallery/src/modules/create-theme/templates/base/astro.config.ts index 905516a..4e4ad56 100644 --- a/gallery/src/modules/create-theme/templates/base/astro.config.ts +++ b/gallery/src/modules/create-theme/templates/base/astro.config.ts @@ -1,11 +1,9 @@ -import fs from 'node:fs'; -import path from 'node:path'; import process from 'node:process'; import { defineConfig } from 'astro/config'; import relativeLinks from 'astro-relative-links'; -import type { AstroIntegration } from 'astro'; +import { preventEmptyContentFiles } from '@simple-photo-gallery/common/theme'; // Dynamically import gallery.json from source path or fallback to local const sourceGalleryPath = process.env.GALLERY_JSON_PATH; @@ -13,33 +11,6 @@ if (!sourceGalleryPath) throw new Error('GALLERY_JSON_PATH environment variable const outputDir = process.env.GALLERY_OUTPUT_DIR || sourceGalleryPath.replace('gallery.json', ''); -/** - * Astro integration to prevent empty content collection files from being generated - */ -function preventEmptyContentFiles(): AstroIntegration { - return { - name: 'prevent-empty-content-files', - hooks: { - 'astro:build:done': ({ dir }) => { - const filesToRemove = ['content-assets.mjs', 'content-modules.mjs']; - for (const fileName of filesToRemove) { - const filePath = path.join(dir.pathname, fileName); - if (fs.existsSync(filePath)) { - try { - const content = fs.readFileSync(filePath, 'utf8'); - if (content.trim() === 'export default new Map();' || content.trim() === '') { - fs.unlinkSync(filePath); - } - } catch { - // Silently ignore errors - } - } - } - }, - }, - }; -} - export default defineConfig({ output: 'static', outDir: outputDir + '/_build', diff --git a/gallery/src/modules/create-theme/templates/base/package.json b/gallery/src/modules/create-theme/templates/base/package.json index b499f84..4b39c31 100644 --- a/gallery/src/modules/create-theme/templates/base/package.json +++ b/gallery/src/modules/create-theme/templates/base/package.json @@ -23,7 +23,6 @@ "astro": "^5.11.0", "astro-relative-links": "^0.4.2", "blurhash": "^2.0.5", - "marked": "^16.4.0", "photoswipe": "^5.4.4" }, "peerDependencies": { diff --git a/gallery/src/modules/create-theme/templates/base/src/components/Hero.astro b/gallery/src/modules/create-theme/templates/base/src/components/Hero.astro index 6c8bdf8..3a1f98d 100644 --- a/gallery/src/modules/create-theme/templates/base/src/components/Hero.astro +++ b/gallery/src/modules/create-theme/templates/base/src/components/Hero.astro @@ -1,154 +1,68 @@ --- -import path from 'node:path'; - -import { getPhotoPath } from '@/utils'; -import { renderMarkdown } from '@/lib/markdown'; +import type { ResolvedHero } from '@simple-photo-gallery/common/theme'; interface Props { - title: string; - description?: string; - thumbsBaseUrl?: string; - headerImage?: string; - headerImageBlurHash?: string; - mediaBaseUrl?: string; + hero: ResolvedHero; } -const { title, description, thumbsBaseUrl, headerImage, headerImageBlurHash, mediaBaseUrl } = Astro.props; - -// Parse description as Markdown if it exists -const parsedDescription: string = description ? await renderMarkdown(description) : ''; - -// Extract basename from headerImage filename, fallback to generic name -const imgBasename = headerImage ? path.basename(headerImage, path.extname(headerImage)) : 'header'; - -// Get the base path for the thumbnails -const thumbnailBasePath = thumbsBaseUrl || 'gallery/images'; - -// Original header photo (fallback) -const headerPhotoPath = getPhotoPath(headerImage || '', mediaBaseUrl); - -const portraitWidths = [360, 480, 720, 1080] as const; -const landscapeWidths = [640, 960, 1280, 1920, 2560, 3840] as const; - -const portraitAvifSrcset = portraitWidths - .map((w) => thumbnailBasePath + '/' + imgBasename + '_portrait_' + w + '.avif ' + w + 'w') - .join(', '); -const portraitJpgSrcset = portraitWidths - .map((w) => thumbnailBasePath + '/' + imgBasename + '_portrait_' + w + '.jpg ' + w + 'w') - .join(', '); - -const landscapeAvifSrcset = landscapeWidths - .map((w) => thumbnailBasePath + '/' + imgBasename + '_landscape_' + w + '.avif ' + w + 'w') - .join(', '); -const landscapeJpgSrcset = landscapeWidths - .map((w) => thumbnailBasePath + '/' + imgBasename + '_landscape_' + w + '.jpg ' + w + 'w') - .join(', '); +const { hero } = Astro.props; --- { - headerImage ? ( + hero.headerImage ? (
- {headerImageBlurHash && } + {hero.headerImageBlurHash && } {/* Portrait */} {/* Landscape */} - - + + {/* Fallback */} - +
-

{title}

- {parsedDescription &&
} +

{hero.title}

+ {hero.parsedDescription && ( +
+ )}
) : (
-

{title}

- {parsedDescription &&
} +

{hero.title}

+ {hero.parsedDescription &&
}
) } diff --git a/yarn.lock b/yarn.lock index 68109ec..a6d87ea 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1677,8 +1677,11 @@ __metadata: typescript-eslint: "npm:^8.38.0" zod: "npm:^4.0.14" peerDependencies: + blurhash: ^2.0.5 photoswipe: ^5.4.4 peerDependenciesMeta: + blurhash: + optional: true photoswipe: optional: true languageName: unknown From b3501959e0b3bff90a5ae55b84ebb12419e43b6b Mon Sep 17 00:00:00 2001 From: rustoma Date: Tue, 20 Jan 2026 20:42:24 +0100 Subject: [PATCH 31/55] refactor: streamline PhotoSwipe module imports in createGalleryLightbox function for improved clarity --- common/src/client.ts | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/common/src/client.ts b/common/src/client.ts index 6e903d0..2fc4890 100644 --- a/common/src/client.ts +++ b/common/src/client.ts @@ -559,8 +559,10 @@ export async function createGalleryLightbox( // Inject enhanced styles - safe to call multiple times injectPhotoSwipeStyles(); - const PhotoSwipe = (await import('photoswipe')).default; - const PhotoSwipeLightboxModule = (await import('photoswipe/lightbox')).default; + const photoswipeModule = await import('photoswipe'); + const PhotoSwipe = photoswipeModule.default; + const lightboxModule = await import('photoswipe/lightbox'); + const PhotoSwipeLightboxModule = lightboxModule.default; const lightbox = new PhotoSwipeLightboxModule({ gallery: options.gallerySelector ?? '.gallery-grid', From 1bd7ec42741193c230d63a4fe46b0c1027f6ddbd Mon Sep 17 00:00:00 2001 From: rustoma Date: Tue, 20 Jan 2026 20:47:20 +0100 Subject: [PATCH 32/55] refactor: format code --- common/src/client.ts | 15 +++----- common/src/theme.ts | 18 ++-------- .../templates/base/src/components/Hero.astro | 4 +-- .../templates/base/src/pages/index.astro | 7 +--- .../base-theme/components/hero/Hero.astro | 36 ++++++++++--------- .../themes/base-theme/pages/index.astro | 6 +--- 6 files changed, 31 insertions(+), 55 deletions(-) diff --git a/common/src/client.ts b/common/src/client.ts index 2fc4890..b90beb1 100644 --- a/common/src/client.ts +++ b/common/src/client.ts @@ -19,11 +19,7 @@ import type PhotoSwipeLightbox from 'photoswipe/lightbox'; * @param width - The width to decode at (default: 32) * @param height - The height to decode at (default: 32) */ -export function decodeBlurhashToCanvas( - canvas: HTMLCanvasElement, - width: number = 32, - height: number = 32, -): void { +export function decodeBlurhashToCanvas(canvas: HTMLCanvasElement, width: number = 32, height: number = 32): void { const blurHashValue = canvas.dataset.blurHash; if (!blurHashValue) return; @@ -553,9 +549,7 @@ export interface GalleryLightboxOptions { * lightbox.init(); * ``` */ -export async function createGalleryLightbox( - options: GalleryLightboxOptions = {}, -): Promise { +export async function createGalleryLightbox(options: GalleryLightboxOptions = {}): Promise { // Inject enhanced styles - safe to call multiple times injectPhotoSwipeStyles(); @@ -597,8 +591,9 @@ export async function createGalleryLightbox( appendTo: 'wrapper', onInit: (el: HTMLElement) => { (lightbox.pswp as PhotoSwipe | undefined)?.on('change', () => { - const currSlideElement = (lightbox.pswp as PhotoSwipe | undefined)?.currSlide?.data - .element as HTMLElement | undefined; + const currSlideElement = (lightbox.pswp as PhotoSwipe | undefined)?.currSlide?.data.element as + | HTMLElement + | undefined; if (currSlideElement) { const caption = (currSlideElement as HTMLElement).dataset.pswpCaption; el.innerHTML = caption || currSlideElement.querySelector('img')?.alt || ''; diff --git a/common/src/theme.ts b/common/src/theme.ts index f4c5374..957e0bc 100644 --- a/common/src/theme.ts +++ b/common/src/theme.ts @@ -4,14 +4,7 @@ import process from 'node:process'; import { marked } from 'marked'; -import type { - GalleryData, - GalleryMetadata, - GallerySection, - HeaderImageVariants, - MediaFile, - SubGallery, -} from './gallery'; +import type { GalleryData, GalleryMetadata, GallerySection, HeaderImageVariants, MediaFile, SubGallery } from './gallery'; // ============================================================================ // Types @@ -163,11 +156,7 @@ export function getRelativePath(resourcePath: string): string { * @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 */ -export function getThumbnailPath( - resourcePath: string, - thumbsBaseUrl?: string, - thumbnailBaseUrl?: string, -): string { +export function getThumbnailPath(resourcePath: string, thumbsBaseUrl?: string, thumbnailBaseUrl?: string): string { // If thumbnail-specific baseUrl is provided, use it and combine with the path if (thumbnailBaseUrl) { return `${thumbnailBaseUrl}/${resourcePath}`; @@ -328,8 +317,7 @@ function resolveSubGallery(subGallery: SubGallery): ResolvedSubGallery { * Resolve hero data with all paths computed and srcsets built. */ async function resolveHero(gallery: GalleryData): Promise { - const { title, description, headerImage, headerImageBlurHash, headerImageVariants, mediaBaseUrl, thumbsBaseUrl } = - gallery; + const { title, description, headerImage, headerImageBlurHash, headerImageVariants, mediaBaseUrl, thumbsBaseUrl } = gallery; const parsedDescription = description ? await renderMarkdown(description) : ''; const imgBasename = headerImage ? path.basename(headerImage, path.extname(headerImage)) : 'header'; diff --git a/gallery/src/modules/create-theme/templates/base/src/components/Hero.astro b/gallery/src/modules/create-theme/templates/base/src/components/Hero.astro index 3a1f98d..e8f1a6b 100644 --- a/gallery/src/modules/create-theme/templates/base/src/components/Hero.astro +++ b/gallery/src/modules/create-theme/templates/base/src/components/Hero.astro @@ -39,9 +39,7 @@ const { hero } = Astro.props;

{hero.title}

- {hero.parsedDescription && ( -
- )} + {hero.parsedDescription &&
}
) : ( diff --git a/gallery/src/modules/create-theme/templates/base/src/pages/index.astro b/gallery/src/modules/create-theme/templates/base/src/pages/index.astro index 5cdb06a..f19b608 100644 --- a/gallery/src/modules/create-theme/templates/base/src/pages/index.astro +++ b/gallery/src/modules/create-theme/templates/base/src/pages/index.astro @@ -36,12 +36,7 @@ const gallery = await resolveGalleryData(raw); data-pswp-type={image.type} data-pswp-caption={image.alt || ''} class="gallery-item"> - {image.alt + {image.alt {image.alt && {image.alt}} ))} diff --git a/themes/modern/src/features/themes/base-theme/components/hero/Hero.astro b/themes/modern/src/features/themes/base-theme/components/hero/Hero.astro index 7e8cab8..f4a9b4a 100644 --- a/themes/modern/src/features/themes/base-theme/components/hero/Hero.astro +++ b/themes/modern/src/features/themes/base-theme/components/hero/Hero.astro @@ -15,22 +15,26 @@ const { hero } = Astro.props; {hero.headerImageBlurHash && } {/* Portrait */} - {hero.srcsets.portraitAvif && ( - - )} - {hero.srcsets.portraitJpg && ( - - )} + { + hero.srcsets.portraitAvif && ( + + ) + } + { + hero.srcsets.portraitJpg && ( + + ) + } {/* Landscape */} {hero.srcsets.landscapeAvif && } diff --git a/themes/modern/src/features/themes/base-theme/pages/index.astro b/themes/modern/src/features/themes/base-theme/pages/index.astro index f14c6ae..43ab722 100644 --- a/themes/modern/src/features/themes/base-theme/pages/index.astro +++ b/themes/modern/src/features/themes/base-theme/pages/index.astro @@ -44,11 +44,7 @@ const showCtaBanner = gallery.ctaBanner === true; ) } - { - gallery.sections.map((section, sectionIndex) => ( - - )) - } + {gallery.sections.map((section, sectionIndex) => )} {showCtaBanner && } From d47b534066bea9f219e09abfbf3cc6f3669efce4 Mon Sep 17 00:00:00 2001 From: rustoma Date: Tue, 20 Jan 2026 20:50:34 +0100 Subject: [PATCH 33/55] chore: clean up imports in Astro config files and ensure consistent usage in Hero component --- .../src/modules/create-theme/templates/base/astro.config.ts | 3 +-- themes/modern/astro.config.ts | 2 +- .../src/features/themes/base-theme/components/hero/Hero.astro | 3 ++- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/gallery/src/modules/create-theme/templates/base/astro.config.ts b/gallery/src/modules/create-theme/templates/base/astro.config.ts index 4e4ad56..3086e80 100644 --- a/gallery/src/modules/create-theme/templates/base/astro.config.ts +++ b/gallery/src/modules/create-theme/templates/base/astro.config.ts @@ -1,10 +1,9 @@ import process from 'node:process'; +import { preventEmptyContentFiles } from '@simple-photo-gallery/common/theme'; import { defineConfig } from 'astro/config'; import relativeLinks from 'astro-relative-links'; -import { preventEmptyContentFiles } from '@simple-photo-gallery/common/theme'; - // Dynamically import gallery.json from source path or fallback to local const sourceGalleryPath = process.env.GALLERY_JSON_PATH; if (!sourceGalleryPath) throw new Error('GALLERY_JSON_PATH environment variable is not set'); diff --git a/themes/modern/astro.config.ts b/themes/modern/astro.config.ts index 2708116..ab5bbc1 100644 --- a/themes/modern/astro.config.ts +++ b/themes/modern/astro.config.ts @@ -1,7 +1,7 @@ +import { preventEmptyContentFiles } from '@simple-photo-gallery/common/theme'; import { defineConfig } from 'astro/config'; import relativeLinks from 'astro-relative-links'; -import { preventEmptyContentFiles } from '@simple-photo-gallery/common/theme'; // Dynamically import gallery.json from source path or fallback to local const sourceGalleryPath = process.env.GALLERY_JSON_PATH; diff --git a/themes/modern/src/features/themes/base-theme/components/hero/Hero.astro b/themes/modern/src/features/themes/base-theme/components/hero/Hero.astro index f4a9b4a..747920d 100644 --- a/themes/modern/src/features/themes/base-theme/components/hero/Hero.astro +++ b/themes/modern/src/features/themes/base-theme/components/hero/Hero.astro @@ -1,7 +1,8 @@ --- +import HeroScrollToGalleryBtn from '@/features/themes/base-theme/components/hero/HeroScrollToGalleryBtn.astro'; + import type { ResolvedHero } from '@simple-photo-gallery/common/theme'; -import HeroScrollToGalleryBtn from '@/features/themes/base-theme/components/hero/HeroScrollToGalleryBtn.astro'; interface Props { hero: ResolvedHero; From 1f219d1d5c4d573bbcf75fa74b6ceeeee80b6e3f Mon Sep 17 00:00:00 2001 From: rustoma Date: Thu, 22 Jan 2026 19:28:30 +0100 Subject: [PATCH 34/55] feat: restructure client and gallery modules --- common/src/client.ts | 739 +------------------ common/src/client/blurhash.ts | 39 + common/src/client/hero-fallback.ts | 98 +++ common/src/client/index.ts | 10 + common/src/client/photoswipe/index.ts | 5 + common/src/client/photoswipe/lightbox.ts | 112 +++ common/src/client/photoswipe/styles.ts | 125 ++++ common/src/client/photoswipe/types.ts | 46 ++ common/src/client/photoswipe/video-plugin.ts | 292 ++++++++ common/src/gallery.ts | 166 +---- common/src/gallery/index.ts | 25 + common/src/gallery/schemas.ts | 139 ++++ common/src/gallery/types.ts | 39 + common/src/theme.ts | 459 +----------- common/src/theme/astro.ts | 38 + common/src/theme/constants.ts | 5 + common/src/theme/index.ts | 20 + common/src/theme/loader.ts | 16 + common/src/theme/markdown.ts | 37 + common/src/theme/paths.ts | 102 +++ common/src/theme/resolver.ts | 173 +++++ common/src/theme/types.ts | 69 ++ 22 files changed, 1393 insertions(+), 1361 deletions(-) create mode 100644 common/src/client/blurhash.ts create mode 100644 common/src/client/hero-fallback.ts create mode 100644 common/src/client/index.ts create mode 100644 common/src/client/photoswipe/index.ts create mode 100644 common/src/client/photoswipe/lightbox.ts create mode 100644 common/src/client/photoswipe/styles.ts create mode 100644 common/src/client/photoswipe/types.ts create mode 100644 common/src/client/photoswipe/video-plugin.ts create mode 100644 common/src/gallery/index.ts create mode 100644 common/src/gallery/schemas.ts create mode 100644 common/src/gallery/types.ts create mode 100644 common/src/theme/astro.ts create mode 100644 common/src/theme/constants.ts create mode 100644 common/src/theme/index.ts create mode 100644 common/src/theme/loader.ts create mode 100644 common/src/theme/markdown.ts create mode 100644 common/src/theme/paths.ts create mode 100644 common/src/theme/resolver.ts create mode 100644 common/src/theme/types.ts diff --git a/common/src/client.ts b/common/src/client.ts index b90beb1..40a7340 100644 --- a/common/src/client.ts +++ b/common/src/client.ts @@ -1,738 +1 @@ -/** - * Client-side utilities for Simple Photo Gallery themes. - * This module contains browser-only code and should only be imported in client contexts. - */ - -import { decode } from 'blurhash'; - -import type PhotoSwipe from 'photoswipe'; -import type PhotoSwipeLightbox from 'photoswipe/lightbox'; - -// ============================================================================ -// Blurhash Utilities -// ============================================================================ - -/** - * Decode a single blurhash and draw it to a canvas element. - * - * @param canvas - The canvas element with a data-blur-hash attribute - * @param width - The width to decode at (default: 32) - * @param height - The height to decode at (default: 32) - */ -export function decodeBlurhashToCanvas(canvas: HTMLCanvasElement, width: number = 32, height: number = 32): void { - const blurHashValue = canvas.dataset.blurHash; - if (!blurHashValue) return; - - const pixels = decode(blurHashValue, width, height); - const ctx = canvas.getContext('2d'); - if (pixels && ctx) { - const imageData = new ImageData(new Uint8ClampedArray(pixels), width, height); - ctx.putImageData(imageData, 0, 0); - } -} - -/** - * Decode and render all blurhash canvases on the page. - * Finds all canvas elements with data-blur-hash attribute and draws the decoded image. - * - * @param selector - CSS selector for canvas elements (default: 'canvas[data-blur-hash]') - * @param width - The width to decode at (default: 32) - * @param height - The height to decode at (default: 32) - */ -export function decodeAllBlurhashes( - selector: string = 'canvas[data-blur-hash]', - width: number = 32, - height: number = 32, -): void { - const canvases = document.querySelectorAll(selector); - for (const canvas of canvases) { - decodeBlurhashToCanvas(canvas, width, height); - } -} - -// ============================================================================ -// Hero Image Fallback -// ============================================================================ - -/** Options for the hero image fallback behavior */ -export interface HeroImageFallbackOptions { - /** CSS selector for the picture element (default: '#hero-bg-picture') */ - pictureSelector?: string; - /** CSS selector for the img element within picture (default: 'img.hero__bg-img') */ - imgSelector?: string; - /** CSS selector for the blurhash canvas element (default: 'canvas[data-blur-hash]') */ - canvasSelector?: string; -} - -/** - * Initialize hero image fallback behavior. - * Handles: - * - Hiding blurhash canvas when image loads successfully - * - Removing source elements and retrying with fallback src on error - * - Keeping blurhash visible if final fallback also fails - * - * @param options - Configuration options for selectors - * - * @example - * ```typescript - * import { initHeroImageFallback } from '@simple-photo-gallery/common/client'; - * - * // Use default selectors - * initHeroImageFallback(); - * - * // Or with custom selectors - * initHeroImageFallback({ - * pictureSelector: '#my-hero-picture', - * imgSelector: 'img.my-hero-img', - * canvasSelector: 'canvas.my-blurhash', - * }); - * ``` - */ -export function initHeroImageFallback(options: HeroImageFallbackOptions = {}): void { - const { - pictureSelector = '#hero-bg-picture', - imgSelector = 'img.hero__bg-img', - canvasSelector = 'canvas[data-blur-hash]', - } = options; - - const picture = document.querySelector(pictureSelector); - const img = picture?.querySelector(imgSelector); - const canvas = document.querySelector(canvasSelector); - - if (!img) return; - - const fallbackSrc = img.getAttribute('src') || ''; - let didFallback = false; - - const hideBlurhash = () => { - if (canvas) { - canvas.style.display = 'none'; - } - }; - - const doFallback = () => { - if (didFallback) return; - didFallback = true; - - if (picture) { - // Remove all elements so the browser does not retry them - for (const sourceEl of picture.querySelectorAll('source')) { - sourceEl.remove(); - } - } - - // Force reload using the src as the final fallback - const current = img.getAttribute('src') || ''; - img.setAttribute('src', ''); - img.setAttribute('src', fallbackSrc || current); - - // If fallback also fails, keep blurhash visible - img.addEventListener( - 'error', - () => { - // Final fallback failed, blurhash stays visible - }, - { once: true }, - ); - - // If fallback succeeds, hide blurhash - img.addEventListener('load', hideBlurhash, { once: true }); - }; - - // Check if image already loaded or failed before script runs - if (img.complete) { - if (img.naturalWidth === 0) { - doFallback(); - } else { - hideBlurhash(); - } - } else { - img.addEventListener('load', hideBlurhash, { once: true }); - } - - img.addEventListener('error', doFallback, { once: true }); -} - -// ============================================================================ -// PhotoSwipe Video Plugin Types -// ============================================================================ - -interface Slide { - content: Content; - height: number; - currZoomLevel: number; - bounds: { center: { y: number } }; - placeholder?: { element: HTMLElement }; - isActive: boolean; -} - -interface Content { - data: SlideData; - element?: HTMLVideoElement | HTMLImageElement | HTMLDivElement; - state?: string; - type?: string; - isAttached?: boolean; - onLoaded?: () => void; - appendImage?: () => void; - slide?: Slide; - _videoPosterImg?: HTMLImageElement; -} - -interface SlideData { - type?: string; - msrc?: string; - videoSrc?: string; - videoSources?: Array<{ src: string; type: string }>; -} - -/** Options for the PhotoSwipe video plugin */ -export interface VideoPluginOptions { - /** HTML attributes to apply to video elements */ - videoAttributes?: Record; - /** Whether to autoplay videos when they become active */ - autoplay?: boolean; - /** Pixels from bottom of video where drag is prevented (for video controls) */ - preventDragOffset?: number; -} - -interface EventData { - content?: Content; - slide?: Slide; - width?: number; - height?: number; - originalEvent?: PointerEvent; - preventDefault?: () => void; -} - -// ============================================================================ -// PhotoSwipe Video Plugin Implementation -// ============================================================================ - -const defaultOptions: VideoPluginOptions = { - videoAttributes: { controls: '', playsinline: '', preload: 'auto' }, - autoplay: true, - preventDragOffset: 40, -}; - -/** - * Check if slide has video content - */ -function isVideoContent(content: Content | Slide): boolean { - return content && 'data' in content && content.data && content.data.type === 'video'; -} - -class VideoContentSetup { - private options: VideoPluginOptions; - - constructor(lightbox: PhotoSwipeLightbox, options: VideoPluginOptions) { - this.options = options; - - this.initLightboxEvents(lightbox); - lightbox.on('init', () => { - if (lightbox.pswp) { - this.initPswpEvents(lightbox.pswp); - } - }); - } - - private initLightboxEvents(lightbox: PhotoSwipeLightbox): void { - lightbox.on('contentLoad', (data: unknown) => this.onContentLoad(data as EventData)); - lightbox.on('contentDestroy', (data: unknown) => this.onContentDestroy(data as { content: Content })); - lightbox.on('contentActivate', (data: unknown) => this.onContentActivate(data as { content: Content })); - lightbox.on('contentDeactivate', (data: unknown) => this.onContentDeactivate(data as { content: Content })); - lightbox.on('contentAppend', (data: unknown) => this.onContentAppend(data as EventData)); - lightbox.on('contentResize', (data: unknown) => this.onContentResize(data as EventData)); - - lightbox.addFilter('isKeepingPlaceholder', (value: unknown, ...args: unknown[]) => - this.isKeepingPlaceholder(value as boolean, args[0] as Content), - ); - lightbox.addFilter('isContentZoomable', (value: unknown, ...args: unknown[]) => - this.isContentZoomable(value as boolean, args[0] as Content), - ); - lightbox.addFilter('useContentPlaceholder', (value: unknown, ...args: unknown[]) => - this.useContentPlaceholder(value as boolean, args[0] as Content), - ); - - lightbox.addFilter('domItemData', (value: unknown, ...args: unknown[]) => { - const itemData = value as Record; - const linkEl = args[1] as HTMLAnchorElement; - - if (itemData.type === 'video' && linkEl) { - if (linkEl.dataset.pswpVideoSources) { - itemData.videoSources = JSON.parse(linkEl.dataset.pswpVideoSources); - } else if (linkEl.dataset.pswpVideoSrc) { - itemData.videoSrc = linkEl.dataset.pswpVideoSrc; - } else { - itemData.videoSrc = linkEl.href; - } - } - return itemData; - }); - } - - private initPswpEvents(pswp: PhotoSwipe): void { - // Prevent dragging when pointer is in bottom part of the video - pswp.on('pointerDown', (data: unknown) => { - const e = data as EventData; - const slide = pswp.currSlide as Slide | undefined; - if (slide && isVideoContent(slide) && this.options.preventDragOffset) { - const origEvent = e.originalEvent; - if (origEvent && origEvent.type === 'pointerdown') { - const videoHeight = Math.ceil(slide.height * slide.currZoomLevel); - const verticalEnding = videoHeight + slide.bounds.center.y; - const pointerYPos = origEvent.pageY - pswp.offset.y; - if (pointerYPos > verticalEnding - this.options.preventDragOffset! && pointerYPos < verticalEnding) { - e.preventDefault?.(); - } - } - } - }); - - // do not append video on nearby slides - pswp.on('appendHeavy', (data: unknown) => { - const e = data as EventData; - if (e.slide && isVideoContent(e.slide) && !e.slide.isActive) { - e.preventDefault?.(); - } - }); - - pswp.on('close', () => { - const slide = pswp.currSlide as Slide | undefined; - if (slide && isVideoContent(slide.content)) { - // Switch from zoom to fade closing transition, - // as zoom transition is choppy for videos - if (!pswp.options.showHideAnimationType || pswp.options.showHideAnimationType === 'zoom') { - pswp.options.showHideAnimationType = 'fade'; - } - - // pause video when closing - this.pauseVideo(slide.content); - } - }); - } - - private onContentDestroy({ content }: { content: Content }): void { - if (isVideoContent(content) && content._videoPosterImg) { - const handleLoad = () => { - if (content._videoPosterImg) { - content._videoPosterImg.removeEventListener('error', handleError); - } - }; - const handleError = () => { - // Error handler - }; - - content._videoPosterImg.addEventListener('load', handleLoad); - content._videoPosterImg.addEventListener('error', handleError); - content._videoPosterImg = undefined; - } - } - - private onContentResize(e: EventData): void { - if (e.content && isVideoContent(e.content)) { - e.preventDefault?.(); - - const width = e.width!; - const height = e.height!; - const content = e.content; - - if (content.element) { - content.element.style.width = width + 'px'; - content.element.style.height = height + 'px'; - } - - if (content.slide && content.slide.placeholder) { - // override placeholder size, so it more accurately matches the video - const placeholderElStyle = content.slide.placeholder.element.style; - placeholderElStyle.transform = 'none'; - placeholderElStyle.width = width + 'px'; - placeholderElStyle.height = height + 'px'; - } - } - } - - private isKeepingPlaceholder(isZoomable: boolean, content: Content): boolean { - if (isVideoContent(content)) { - return false; - } - return isZoomable; - } - - private isContentZoomable(isZoomable: boolean, content: Content): boolean { - if (isVideoContent(content)) { - return false; - } - return isZoomable; - } - - private onContentActivate({ content }: { content: Content }): void { - if (isVideoContent(content) && this.options.autoplay) { - this.playVideo(content); - } - } - - private onContentDeactivate({ content }: { content: Content }): void { - if (isVideoContent(content)) { - this.pauseVideo(content); - } - } - - private onContentAppend(e: EventData): void { - if (e.content && isVideoContent(e.content)) { - e.preventDefault?.(); - e.content.isAttached = true; - e.content.appendImage?.(); - } - } - - private onContentLoad(e: EventData): void { - const content = e.content!; - - if (!isVideoContent(content)) { - return; - } - - // stop default content load - e.preventDefault?.(); - - if (content.element) { - return; - } - - content.state = 'loading'; - content.type = 'video'; - - content.element = document.createElement('video'); - - if (this.options.videoAttributes) { - for (const key in this.options.videoAttributes) { - content.element.setAttribute(key, this.options.videoAttributes[key] || ''); - } - } - - content.element.setAttribute('poster', content.data.msrc || ''); - - this.preloadVideoPoster(content, content.data.msrc); - - content.element.style.position = 'absolute'; - content.element.style.left = '0'; - content.element.style.top = '0'; - - if (content.data.videoSources) { - for (const source of content.data.videoSources) { - const sourceEl = document.createElement('source'); - sourceEl.src = source.src; - sourceEl.type = source.type; - content.element.append(sourceEl); - } - } else if (content.data.videoSrc) { - content.element.src = content.data.videoSrc; - } - } - - private preloadVideoPoster(content: Content, src?: string): void { - if (!content._videoPosterImg && src) { - content._videoPosterImg = new Image(); - content._videoPosterImg.src = src; - if (content._videoPosterImg.complete) { - content.onLoaded?.(); - } else { - content._videoPosterImg.addEventListener('load', () => { - content.onLoaded?.(); - }); - content._videoPosterImg.addEventListener('error', () => { - content.onLoaded?.(); - }); - } - } - } - - private playVideo(content: Content): void { - if (content.element) { - (content.element as HTMLVideoElement).play(); - } - } - - private pauseVideo(content: Content): void { - if (content.element) { - (content.element as HTMLVideoElement).pause(); - } - } - - private useContentPlaceholder(usePlaceholder: boolean, content: Content): boolean { - if (isVideoContent(content)) { - return true; - } - return usePlaceholder; - } -} - -/** - * PhotoSwipe plugin that adds video support to the lightbox. - * Videos are automatically detected by the `data-pswp-type="video"` attribute - * on gallery links. - * - * @example - * ```typescript - * import PhotoSwipe from 'photoswipe'; - * import PhotoSwipeLightbox from 'photoswipe/lightbox'; - * import { PhotoSwipeVideoPlugin } from '@simple-photo-gallery/common/client'; - * - * const lightbox = new PhotoSwipeLightbox({ - * gallery: '.gallery', - * children: 'a', - * pswpModule: PhotoSwipe, - * }); - * - * new PhotoSwipeVideoPlugin(lightbox); - * lightbox.init(); - * ``` - */ -export class PhotoSwipeVideoPlugin { - constructor(lightbox: PhotoSwipeLightbox, options: VideoPluginOptions = {}) { - new VideoContentSetup(lightbox, { - ...defaultOptions, - ...options, - }); - } -} - -// ============================================================================ -// Gallery Lightbox Factory -// ============================================================================ - -/** Options for creating a gallery lightbox */ -export interface GalleryLightboxOptions { - /** CSS selector for gallery container (default: '.gallery-grid') */ - gallerySelector?: string; - /** CSS selector for gallery items within container (default: 'a') */ - childrenSelector?: string; - /** Animation duration when opening in ms (default: 300) */ - showAnimationDuration?: number; - /** Animation duration when closing in ms (default: 300) */ - hideAnimationDuration?: number; - /** Enable mouse wheel zoom (default: true) */ - wheelToZoom?: boolean; - /** Loop back to first image after last (default: false) */ - loop?: boolean; - /** Background opacity 0-1 (default: 1) */ - bgOpacity?: number; - /** Options for the video plugin */ - videoPluginOptions?: VideoPluginOptions; - /** Enable slide-in animations when changing slides (default: true) */ - slideAnimations?: boolean; - /** Enable custom caption UI from data-pswp-caption attribute (default: true) */ - enableCaptions?: boolean; -} - -/** - * Create a PhotoSwipe lightbox with sensible defaults and video support. - * Returns the lightbox instance for further customization before calling init(). - * - * @example - * ```typescript - * import { createGalleryLightbox } from '@simple-photo-gallery/common/client'; - * import 'photoswipe/style.css'; - * - * // Basic usage - * const lightbox = await createGalleryLightbox(); - * lightbox.init(); - * - * // With custom options - * const lightbox = await createGalleryLightbox({ - * gallerySelector: '.my-gallery', - * loop: true, - * }); - * - * // Add custom event handlers before init - * lightbox.on('change', () => console.log('slide changed')); - * lightbox.init(); - * ``` - */ -export async function createGalleryLightbox(options: GalleryLightboxOptions = {}): Promise { - // Inject enhanced styles - safe to call multiple times - injectPhotoSwipeStyles(); - - const photoswipeModule = await import('photoswipe'); - const PhotoSwipe = photoswipeModule.default; - const lightboxModule = await import('photoswipe/lightbox'); - const PhotoSwipeLightboxModule = lightboxModule.default; - - const lightbox = new PhotoSwipeLightboxModule({ - gallery: options.gallerySelector ?? '.gallery-grid', - children: options.childrenSelector ?? 'a', - pswpModule: PhotoSwipe, - showAnimationDuration: options.showAnimationDuration ?? 300, - hideAnimationDuration: options.hideAnimationDuration ?? 300, - wheelToZoom: options.wheelToZoom ?? true, - loop: options.loop ?? false, - bgOpacity: options.bgOpacity ?? 1, - }); - - new PhotoSwipeVideoPlugin(lightbox, options.videoPluginOptions); - - // Slide animations (enabled by default) - if (options.slideAnimations !== false) { - lightbox.on('contentDeactivate', ({ content }: { content: { element?: HTMLElement } }) => { - content.element?.classList.remove('pswp__img--in-viewport'); - }); - lightbox.on('contentActivate', ({ content }: { content: { element?: HTMLElement } }) => { - content.element?.classList.add('pswp__img--in-viewport'); - }); - } - - // Custom caption UI (enabled by default) - if (options.enableCaptions !== false) { - lightbox.on('uiRegister', () => { - (lightbox.pswp as PhotoSwipe | undefined)?.ui?.registerElement({ - name: 'custom-caption', - isButton: false, - className: 'pswp__caption', - appendTo: 'wrapper', - onInit: (el: HTMLElement) => { - (lightbox.pswp as PhotoSwipe | undefined)?.on('change', () => { - const currSlideElement = (lightbox.pswp as PhotoSwipe | undefined)?.currSlide?.data.element as - | HTMLElement - | undefined; - if (currSlideElement) { - const caption = (currSlideElement as HTMLElement).dataset.pswpCaption; - el.innerHTML = caption || currSlideElement.querySelector('img')?.alt || ''; - } - }); - }, - }); - }); - } - - return lightbox; -} - -// ============================================================================ -// PhotoSwipe Enhanced Styles -// ============================================================================ - -const PHOTOSWIPE_STYLES = ` -/* PhotoSwipe enhanced styles */ -.pswp .pswp__bg { - --pswp-bg: rgba(0, 0, 0, 1); -} - -.pswp__counter { - color: white; - font-size: 1rem; -} - -.pswp__button { - color: white; - opacity: 0.8; - transition: opacity 0.3s ease; -} - -.pswp__button:hover { - opacity: 1; -} - -.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: rgba(128, 128, 128, 0.3); - backdrop-filter: blur(8px); - -webkit-backdrop-filter: blur(8px); - color: white; - padding: 16px; - border-radius: 16px; - margin: 1rem; - box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3); -} - -@media (max-width: 768px) { - .pswp__caption .image-caption { - padding: 8px 16px; - font-size: 0.8rem; - margin: 8px 0; - } -} - -.pswp__caption__center { - text-align: center; - max-width: 42rem; - margin: 0 auto; -} - -.pswp__caption h3 { - font-size: 1.5rem; - font-weight: 600; - margin-bottom: 0.5rem; - text-shadow: 0 2px 4px rgba(0, 0, 0, 0.3); -} - -.pswp__caption p { - font-size: 1rem; - 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: 0.95rem; - opacity: 0.9; - font-weight: 300; - font-style: italic; -} - -/* Slide-in animation */ -.pswp__img { - opacity: 0; -} - -.pswp__img--in-viewport { - animation: pswp-slideIn 0.6s ease-out forwards; -} - -@keyframes pswp-slideIn { - from { opacity: 0; } - to { opacity: 1; } -} -`; - -/** - * Inject PhotoSwipe enhanced styles into the document. - * Includes custom styles for captions, animations, and button hover effects. - * Safe to call multiple times - will only inject once. - * Called automatically by createGalleryLightbox(), so you typically don't need to call this directly. - * - * Note: Base PhotoSwipe CSS (photoswipe/style.css) must still be imported in your theme. - * This function only injects the enhanced SPG-specific styles. - * - * @example - * ```typescript - * import { createGalleryLightbox } from '@simple-photo-gallery/common/client'; - * import 'photoswipe/style.css'; // Required base styles - * - * const lightbox = await createGalleryLightbox(); - * lightbox.init(); - * ``` - */ -export function injectPhotoSwipeStyles(): void { - if (document.querySelector('#spg-photoswipe-styles')) return; - - const style = document.createElement('style'); - style.id = 'spg-photoswipe-styles'; - style.textContent = PHOTOSWIPE_STYLES; - document.head.append(style); -} +export * from './client/index'; diff --git a/common/src/client/blurhash.ts b/common/src/client/blurhash.ts new file mode 100644 index 0000000..9b27352 --- /dev/null +++ b/common/src/client/blurhash.ts @@ -0,0 +1,39 @@ +import { decode } from 'blurhash'; + +/** + * Decode a single blurhash and draw it to a canvas element. + * + * @param canvas - The canvas element with a data-blur-hash attribute + * @param width - The width to decode at (default: 32) + * @param height - The height to decode at (default: 32) + */ +export function decodeBlurhashToCanvas(canvas: HTMLCanvasElement, width: number = 32, height: number = 32): void { + const blurHashValue = canvas.dataset.blurHash; + if (!blurHashValue) return; + + const pixels = decode(blurHashValue, width, height); + const ctx = canvas.getContext('2d'); + if (pixels && ctx) { + const imageData = new ImageData(new Uint8ClampedArray(pixels), width, height); + ctx.putImageData(imageData, 0, 0); + } +} + +/** + * Decode and render all blurhash canvases on the page. + * Finds all canvas elements with data-blur-hash attribute and draws the decoded image. + * + * @param selector - CSS selector for canvas elements (default: 'canvas[data-blur-hash]') + * @param width - The width to decode at (default: 32) + * @param height - The height to decode at (default: 32) + */ +export function decodeAllBlurhashes( + selector: string = 'canvas[data-blur-hash]', + width: number = 32, + height: number = 32, +): void { + const canvases = document.querySelectorAll(selector); + for (const canvas of canvases) { + decodeBlurhashToCanvas(canvas, width, height); + } +} diff --git a/common/src/client/hero-fallback.ts b/common/src/client/hero-fallback.ts new file mode 100644 index 0000000..d1a8184 --- /dev/null +++ b/common/src/client/hero-fallback.ts @@ -0,0 +1,98 @@ +/** Options for the hero image fallback behavior */ +export interface HeroImageFallbackOptions { + /** CSS selector for the picture element (default: '#hero-bg-picture') */ + pictureSelector?: string; + /** CSS selector for the img element within picture (default: 'img.hero__bg-img') */ + imgSelector?: string; + /** CSS selector for the blurhash canvas element (default: 'canvas[data-blur-hash]') */ + canvasSelector?: string; +} + +/** + * Initialize hero image fallback behavior. + * Handles: + * - Hiding blurhash canvas when image loads successfully + * - Removing source elements and retrying with fallback src on error + * - Keeping blurhash visible if final fallback also fails + * + * @param options - Configuration options for selectors + * + * @example + * ```typescript + * import { initHeroImageFallback } from '@simple-photo-gallery/common/client'; + * + * // Use default selectors + * initHeroImageFallback(); + * + * // Or with custom selectors + * initHeroImageFallback({ + * pictureSelector: '#my-hero-picture', + * imgSelector: 'img.my-hero-img', + * canvasSelector: 'canvas.my-blurhash', + * }); + * ``` + */ +export function initHeroImageFallback(options: HeroImageFallbackOptions = {}): void { + const { + pictureSelector = '#hero-bg-picture', + imgSelector = 'img.hero__bg-img', + canvasSelector = 'canvas[data-blur-hash]', + } = options; + + const picture = document.querySelector(pictureSelector); + const img = picture?.querySelector(imgSelector); + const canvas = document.querySelector(canvasSelector); + + if (!img) return; + + const fallbackSrc = img.getAttribute('src') || ''; + let didFallback = false; + + const hideBlurhash = () => { + if (canvas) { + canvas.style.display = 'none'; + } + }; + + const doFallback = () => { + if (didFallback) return; + didFallback = true; + + if (picture) { + // Remove all elements so the browser does not retry them + for (const sourceEl of picture.querySelectorAll('source')) { + sourceEl.remove(); + } + } + + // Force reload using the src as the final fallback + const current = img.getAttribute('src') || ''; + img.setAttribute('src', ''); + img.setAttribute('src', fallbackSrc || current); + + // If fallback also fails, keep blurhash visible + img.addEventListener( + 'error', + () => { + // Final fallback failed, blurhash stays visible + }, + { once: true }, + ); + + // If fallback succeeds, hide blurhash + img.addEventListener('load', hideBlurhash, { once: true }); + }; + + // Check if image already loaded or failed before script runs + if (img.complete) { + if (img.naturalWidth === 0) { + doFallback(); + } else { + hideBlurhash(); + } + } else { + img.addEventListener('load', hideBlurhash, { once: true }); + } + + img.addEventListener('error', doFallback, { once: true }); +} diff --git a/common/src/client/index.ts b/common/src/client/index.ts new file mode 100644 index 0000000..4170831 --- /dev/null +++ b/common/src/client/index.ts @@ -0,0 +1,10 @@ +// Blurhash utilities +export { decodeAllBlurhashes, decodeBlurhashToCanvas } from './blurhash'; + +// Hero image fallback +export type { HeroImageFallbackOptions } from './hero-fallback'; +export { initHeroImageFallback } from './hero-fallback'; + +// PhotoSwipe integration +export type { GalleryLightboxOptions, VideoPluginOptions } from './photoswipe'; +export { createGalleryLightbox, injectPhotoSwipeStyles, PhotoSwipeVideoPlugin } from './photoswipe'; diff --git a/common/src/client/photoswipe/index.ts b/common/src/client/photoswipe/index.ts new file mode 100644 index 0000000..9cc7da4 --- /dev/null +++ b/common/src/client/photoswipe/index.ts @@ -0,0 +1,5 @@ +export type { GalleryLightboxOptions } from './lightbox'; +export { createGalleryLightbox } from './lightbox'; +export { injectPhotoSwipeStyles } from './styles'; +export type { VideoPluginOptions } from './types'; +export { PhotoSwipeVideoPlugin } from './video-plugin'; diff --git a/common/src/client/photoswipe/lightbox.ts b/common/src/client/photoswipe/lightbox.ts new file mode 100644 index 0000000..01862b7 --- /dev/null +++ b/common/src/client/photoswipe/lightbox.ts @@ -0,0 +1,112 @@ +import type PhotoSwipe from 'photoswipe'; +import type PhotoSwipeLightbox from 'photoswipe/lightbox'; + +import { injectPhotoSwipeStyles } from './styles'; +import type { VideoPluginOptions } from './types'; +import { PhotoSwipeVideoPlugin } from './video-plugin'; + +/** Options for creating a gallery lightbox */ +export interface GalleryLightboxOptions { + /** CSS selector for gallery container (default: '.gallery-grid') */ + gallerySelector?: string; + /** CSS selector for gallery items within container (default: 'a') */ + childrenSelector?: string; + /** Animation duration when opening in ms (default: 300) */ + showAnimationDuration?: number; + /** Animation duration when closing in ms (default: 300) */ + hideAnimationDuration?: number; + /** Enable mouse wheel zoom (default: true) */ + wheelToZoom?: boolean; + /** Loop back to first image after last (default: false) */ + loop?: boolean; + /** Background opacity 0-1 (default: 1) */ + bgOpacity?: number; + /** Options for the video plugin */ + videoPluginOptions?: VideoPluginOptions; + /** Enable slide-in animations when changing slides (default: true) */ + slideAnimations?: boolean; + /** Enable custom caption UI from data-pswp-caption attribute (default: true) */ + enableCaptions?: boolean; +} + +/** + * Create a PhotoSwipe lightbox with sensible defaults and video support. + * Returns the lightbox instance for further customization before calling init(). + * + * @example + * ```typescript + * import { createGalleryLightbox } from '@simple-photo-gallery/common/client'; + * import 'photoswipe/style.css'; + * + * // Basic usage + * const lightbox = await createGalleryLightbox(); + * lightbox.init(); + * + * // With custom options + * const lightbox = await createGalleryLightbox({ + * gallerySelector: '.my-gallery', + * loop: true, + * }); + * + * // Add custom event handlers before init + * lightbox.on('change', () => console.log('slide changed')); + * lightbox.init(); + * ``` + */ +export async function createGalleryLightbox(options: GalleryLightboxOptions = {}): Promise { + // Inject enhanced styles - safe to call multiple times + injectPhotoSwipeStyles(); + + const photoswipeModule = await import('photoswipe'); + const PhotoSwipe = photoswipeModule.default; + const lightboxModule = await import('photoswipe/lightbox'); + const PhotoSwipeLightboxModule = lightboxModule.default; + + const lightbox = new PhotoSwipeLightboxModule({ + gallery: options.gallerySelector ?? '.gallery-grid', + children: options.childrenSelector ?? 'a', + pswpModule: PhotoSwipe, + showAnimationDuration: options.showAnimationDuration ?? 300, + hideAnimationDuration: options.hideAnimationDuration ?? 300, + wheelToZoom: options.wheelToZoom ?? true, + loop: options.loop ?? false, + bgOpacity: options.bgOpacity ?? 1, + }); + + new PhotoSwipeVideoPlugin(lightbox, options.videoPluginOptions); + + // Slide animations (enabled by default) + if (options.slideAnimations !== false) { + lightbox.on('contentDeactivate', ({ content }: { content: { element?: HTMLElement } }) => { + content.element?.classList.remove('pswp__img--in-viewport'); + }); + lightbox.on('contentActivate', ({ content }: { content: { element?: HTMLElement } }) => { + content.element?.classList.add('pswp__img--in-viewport'); + }); + } + + // Custom caption UI (enabled by default) + if (options.enableCaptions !== false) { + lightbox.on('uiRegister', () => { + (lightbox.pswp as PhotoSwipe | undefined)?.ui?.registerElement({ + name: 'custom-caption', + isButton: false, + className: 'pswp__caption', + appendTo: 'wrapper', + onInit: (el: HTMLElement) => { + (lightbox.pswp as PhotoSwipe | undefined)?.on('change', () => { + const currSlideElement = (lightbox.pswp as PhotoSwipe | undefined)?.currSlide?.data.element as + | HTMLElement + | undefined; + if (currSlideElement) { + const caption = (currSlideElement as HTMLElement).dataset.pswpCaption; + el.innerHTML = caption || currSlideElement.querySelector('img')?.alt || ''; + } + }); + }, + }); + }); + } + + return lightbox; +} diff --git a/common/src/client/photoswipe/styles.ts b/common/src/client/photoswipe/styles.ts new file mode 100644 index 0000000..de8554a --- /dev/null +++ b/common/src/client/photoswipe/styles.ts @@ -0,0 +1,125 @@ +const PHOTOSWIPE_STYLES = ` +/* PhotoSwipe enhanced styles */ +.pswp .pswp__bg { + --pswp-bg: rgba(0, 0, 0, 1); +} + +.pswp__counter { + color: white; + font-size: 1rem; +} + +.pswp__button { + color: white; + opacity: 0.8; + transition: opacity 0.3s ease; +} + +.pswp__button:hover { + opacity: 1; +} + +.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: rgba(128, 128, 128, 0.3); + backdrop-filter: blur(8px); + -webkit-backdrop-filter: blur(8px); + color: white; + padding: 16px; + border-radius: 16px; + margin: 1rem; + box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3); +} + +@media (max-width: 768px) { + .pswp__caption .image-caption { + padding: 8px 16px; + font-size: 0.8rem; + margin: 8px 0; + } +} + +.pswp__caption__center { + text-align: center; + max-width: 42rem; + margin: 0 auto; +} + +.pswp__caption h3 { + font-size: 1.5rem; + font-weight: 600; + margin-bottom: 0.5rem; + text-shadow: 0 2px 4px rgba(0, 0, 0, 0.3); +} + +.pswp__caption p { + font-size: 1rem; + 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: 0.95rem; + opacity: 0.9; + font-weight: 300; + font-style: italic; +} + +/* Slide-in animation */ +.pswp__img { + opacity: 0; +} + +.pswp__img--in-viewport { + animation: pswp-slideIn 0.6s ease-out forwards; +} + +@keyframes pswp-slideIn { + from { opacity: 0; } + to { opacity: 1; } +} +`; + +/** + * Inject PhotoSwipe enhanced styles into the document. + * Includes custom styles for captions, animations, and button hover effects. + * Safe to call multiple times - will only inject once. + * Called automatically by createGalleryLightbox(), so you typically don't need to call this directly. + * + * Note: Base PhotoSwipe CSS (photoswipe/style.css) must still be imported in your theme. + * This function only injects the enhanced SPG-specific styles. + * + * @example + * ```typescript + * import { createGalleryLightbox } from '@simple-photo-gallery/common/client'; + * import 'photoswipe/style.css'; // Required base styles + * + * const lightbox = await createGalleryLightbox(); + * lightbox.init(); + * ``` + */ +export function injectPhotoSwipeStyles(): void { + if (document.querySelector('#spg-photoswipe-styles')) return; + + const style = document.createElement('style'); + style.id = 'spg-photoswipe-styles'; + style.textContent = PHOTOSWIPE_STYLES; + document.head.append(style); +} diff --git a/common/src/client/photoswipe/types.ts b/common/src/client/photoswipe/types.ts new file mode 100644 index 0000000..edfb02b --- /dev/null +++ b/common/src/client/photoswipe/types.ts @@ -0,0 +1,46 @@ +export interface Slide { + content: Content; + height: number; + currZoomLevel: number; + bounds: { center: { y: number } }; + placeholder?: { element: HTMLElement }; + isActive: boolean; +} + +export interface Content { + data: SlideData; + element?: HTMLVideoElement | HTMLImageElement | HTMLDivElement; + state?: string; + type?: string; + isAttached?: boolean; + onLoaded?: () => void; + appendImage?: () => void; + slide?: Slide; + _videoPosterImg?: HTMLImageElement; +} + +export interface SlideData { + type?: string; + msrc?: string; + videoSrc?: string; + videoSources?: Array<{ src: string; type: string }>; +} + +/** Options for the PhotoSwipe video plugin */ +export interface VideoPluginOptions { + /** HTML attributes to apply to video elements */ + videoAttributes?: Record; + /** Whether to autoplay videos when they become active */ + autoplay?: boolean; + /** Pixels from bottom of video where drag is prevented (for video controls) */ + preventDragOffset?: number; +} + +export interface EventData { + content?: Content; + slide?: Slide; + width?: number; + height?: number; + originalEvent?: PointerEvent; + preventDefault?: () => void; +} diff --git a/common/src/client/photoswipe/video-plugin.ts b/common/src/client/photoswipe/video-plugin.ts new file mode 100644 index 0000000..d1cff31 --- /dev/null +++ b/common/src/client/photoswipe/video-plugin.ts @@ -0,0 +1,292 @@ +import type { Content, EventData, Slide, VideoPluginOptions } from './types'; +import type PhotoSwipe from 'photoswipe'; +import type PhotoSwipeLightbox from 'photoswipe/lightbox'; + +const defaultOptions: VideoPluginOptions = { + videoAttributes: { controls: '', playsinline: '', preload: 'auto' }, + autoplay: true, + preventDragOffset: 40, +}; + +/** + * Check if slide has video content + */ +function isVideoContent(content: Content | Slide): boolean { + return content && 'data' in content && content.data && content.data.type === 'video'; +} + +class VideoContentSetup { + private options: VideoPluginOptions; + + constructor(lightbox: PhotoSwipeLightbox, options: VideoPluginOptions) { + this.options = options; + + this.initLightboxEvents(lightbox); + lightbox.on('init', () => { + if (lightbox.pswp) { + this.initPswpEvents(lightbox.pswp); + } + }); + } + + private initLightboxEvents(lightbox: PhotoSwipeLightbox): void { + lightbox.on('contentLoad', (data: unknown) => this.onContentLoad(data as EventData)); + lightbox.on('contentDestroy', (data: unknown) => this.onContentDestroy(data as { content: Content })); + lightbox.on('contentActivate', (data: unknown) => this.onContentActivate(data as { content: Content })); + lightbox.on('contentDeactivate', (data: unknown) => this.onContentDeactivate(data as { content: Content })); + lightbox.on('contentAppend', (data: unknown) => this.onContentAppend(data as EventData)); + lightbox.on('contentResize', (data: unknown) => this.onContentResize(data as EventData)); + + lightbox.addFilter('isKeepingPlaceholder', (value: unknown, ...args: unknown[]) => + this.isKeepingPlaceholder(value as boolean, args[0] as Content), + ); + lightbox.addFilter('isContentZoomable', (value: unknown, ...args: unknown[]) => + this.isContentZoomable(value as boolean, args[0] as Content), + ); + lightbox.addFilter('useContentPlaceholder', (value: unknown, ...args: unknown[]) => + this.useContentPlaceholder(value as boolean, args[0] as Content), + ); + + lightbox.addFilter('domItemData', (value: unknown, ...args: unknown[]) => { + const itemData = value as Record; + const linkEl = args[1] as HTMLAnchorElement; + + if (itemData.type === 'video' && linkEl) { + if (linkEl.dataset.pswpVideoSources) { + itemData.videoSources = JSON.parse(linkEl.dataset.pswpVideoSources); + } else if (linkEl.dataset.pswpVideoSrc) { + itemData.videoSrc = linkEl.dataset.pswpVideoSrc; + } else { + itemData.videoSrc = linkEl.href; + } + } + return itemData; + }); + } + + private initPswpEvents(pswp: PhotoSwipe): void { + // Prevent dragging when pointer is in bottom part of the video + pswp.on('pointerDown', (data: unknown) => { + const e = data as EventData; + const slide = pswp.currSlide as Slide | undefined; + if (slide && isVideoContent(slide) && this.options.preventDragOffset) { + const origEvent = e.originalEvent; + if (origEvent && origEvent.type === 'pointerdown') { + const videoHeight = Math.ceil(slide.height * slide.currZoomLevel); + const verticalEnding = videoHeight + slide.bounds.center.y; + const pointerYPos = origEvent.pageY - pswp.offset.y; + if (pointerYPos > verticalEnding - this.options.preventDragOffset! && pointerYPos < verticalEnding) { + e.preventDefault?.(); + } + } + } + }); + + // do not append video on nearby slides + pswp.on('appendHeavy', (data: unknown) => { + const e = data as EventData; + if (e.slide && isVideoContent(e.slide) && !e.slide.isActive) { + e.preventDefault?.(); + } + }); + + pswp.on('close', () => { + const slide = pswp.currSlide as Slide | undefined; + if (slide && isVideoContent(slide.content)) { + // Switch from zoom to fade closing transition, + // as zoom transition is choppy for videos + if (!pswp.options.showHideAnimationType || pswp.options.showHideAnimationType === 'zoom') { + pswp.options.showHideAnimationType = 'fade'; + } + + // pause video when closing + this.pauseVideo(slide.content); + } + }); + } + + private onContentDestroy({ content }: { content: Content }): void { + if (isVideoContent(content) && content._videoPosterImg) { + const handleLoad = () => { + if (content._videoPosterImg) { + content._videoPosterImg.removeEventListener('error', handleError); + } + }; + const handleError = () => { + // Error handler + }; + + content._videoPosterImg.addEventListener('load', handleLoad); + content._videoPosterImg.addEventListener('error', handleError); + content._videoPosterImg = undefined; + } + } + + private onContentResize(e: EventData): void { + if (e.content && isVideoContent(e.content)) { + e.preventDefault?.(); + + const width = e.width!; + const height = e.height!; + const content = e.content; + + if (content.element) { + content.element.style.width = width + 'px'; + content.element.style.height = height + 'px'; + } + + if (content.slide && content.slide.placeholder) { + // override placeholder size, so it more accurately matches the video + const placeholderElStyle = content.slide.placeholder.element.style; + placeholderElStyle.transform = 'none'; + placeholderElStyle.width = width + 'px'; + placeholderElStyle.height = height + 'px'; + } + } + } + + private isKeepingPlaceholder(isZoomable: boolean, content: Content): boolean { + if (isVideoContent(content)) { + return false; + } + return isZoomable; + } + + private isContentZoomable(isZoomable: boolean, content: Content): boolean { + if (isVideoContent(content)) { + return false; + } + return isZoomable; + } + + private onContentActivate({ content }: { content: Content }): void { + if (isVideoContent(content) && this.options.autoplay) { + this.playVideo(content); + } + } + + private onContentDeactivate({ content }: { content: Content }): void { + if (isVideoContent(content)) { + this.pauseVideo(content); + } + } + + private onContentAppend(e: EventData): void { + if (e.content && isVideoContent(e.content)) { + e.preventDefault?.(); + e.content.isAttached = true; + e.content.appendImage?.(); + } + } + + private onContentLoad(e: EventData): void { + const content = e.content!; + + if (!isVideoContent(content)) { + return; + } + + // stop default content load + e.preventDefault?.(); + + if (content.element) { + return; + } + + content.state = 'loading'; + content.type = 'video'; + + content.element = document.createElement('video'); + + if (this.options.videoAttributes) { + for (const key in this.options.videoAttributes) { + content.element.setAttribute(key, this.options.videoAttributes[key] || ''); + } + } + + content.element.setAttribute('poster', content.data.msrc || ''); + + this.preloadVideoPoster(content, content.data.msrc); + + content.element.style.position = 'absolute'; + content.element.style.left = '0'; + content.element.style.top = '0'; + + if (content.data.videoSources) { + for (const source of content.data.videoSources) { + const sourceEl = document.createElement('source'); + sourceEl.src = source.src; + sourceEl.type = source.type; + content.element.append(sourceEl); + } + } else if (content.data.videoSrc) { + content.element.src = content.data.videoSrc; + } + } + + private preloadVideoPoster(content: Content, src?: string): void { + if (!content._videoPosterImg && src) { + content._videoPosterImg = new Image(); + content._videoPosterImg.src = src; + if (content._videoPosterImg.complete) { + content.onLoaded?.(); + } else { + content._videoPosterImg.addEventListener('load', () => { + content.onLoaded?.(); + }); + content._videoPosterImg.addEventListener('error', () => { + content.onLoaded?.(); + }); + } + } + } + + private playVideo(content: Content): void { + if (content.element) { + (content.element as HTMLVideoElement).play(); + } + } + + private pauseVideo(content: Content): void { + if (content.element) { + (content.element as HTMLVideoElement).pause(); + } + } + + private useContentPlaceholder(usePlaceholder: boolean, content: Content): boolean { + if (isVideoContent(content)) { + return true; + } + return usePlaceholder; + } +} + +/** + * PhotoSwipe plugin that adds video support to the lightbox. + * Videos are automatically detected by the `data-pswp-type="video"` attribute + * on gallery links. + * + * @example + * ```typescript + * import PhotoSwipe from 'photoswipe'; + * import PhotoSwipeLightbox from 'photoswipe/lightbox'; + * import { PhotoSwipeVideoPlugin } from '@simple-photo-gallery/common/client'; + * + * const lightbox = new PhotoSwipeLightbox({ + * gallery: '.gallery', + * children: 'a', + * pswpModule: PhotoSwipe, + * }); + * + * new PhotoSwipeVideoPlugin(lightbox); + * lightbox.init(); + * ``` + */ +export class PhotoSwipeVideoPlugin { + constructor(lightbox: PhotoSwipeLightbox, options: VideoPluginOptions = {}) { + new VideoContentSetup(lightbox, { + ...defaultOptions, + ...options, + }); + } +} diff --git a/common/src/gallery.ts b/common/src/gallery.ts index 94902bb..ba85e46 100644 --- a/common/src/gallery.ts +++ b/common/src/gallery.ts @@ -1,165 +1 @@ -import { z } from 'zod'; - -/** Zod schema for thumbnail metadata including path and dimensions */ -export const ThumbnailSchema = z.object({ - baseUrl: z.string().optional(), - path: z.string(), - pathRetina: z.string(), - width: z.number(), - height: z.number(), - blurHash: z.string().optional(), -}); - -/** Zod schema for media file metadata including type, dimensions, and thumbnail info */ -export const MediaFileSchema = z.object({ - type: z.enum(['image', 'video']), - filename: z.string(), - url: z.string().optional(), - alt: z.string().optional(), - width: z.number(), - height: z.number(), - thumbnail: ThumbnailSchema.optional(), - lastMediaTimestamp: z.string().optional(), -}); - -/** Zod schema for media file with path (deprecated) */ -export const MediaFileDeprecatedSchema = z.object({ - type: z.enum(['image', 'video']), - path: z.string(), - alt: z.string().optional(), - width: z.number(), - height: z.number(), - thumbnail: ThumbnailSchema.optional(), - lastMediaTimestamp: z.string().optional(), -}); - -/** Zod schema for a gallery section containing title, description, and media files */ -export const GallerySectionSchema = z.object({ - title: z.string().optional(), - description: z.string().optional(), - images: z.array(MediaFileSchema), -}); - -/** Zod schema for a gallery section containing title, description, and media files (deprecated) */ -export const GallerySectionDeprecatedSchema = z.object({ - title: z.string().optional(), - description: z.string().optional(), - images: z.array(MediaFileDeprecatedSchema), -}); - -/** Zod schema for sub-gallery metadata including title, header image, and path */ -export const SubGallerySchema = z.object({ - title: z.string(), - headerImage: z.string(), - path: z.string(), -}); - -/** Zod schema for portrait image size variants */ -const PortraitSizesSchema = z.object({ - 360: z.string().optional(), - 480: z.string().optional(), - 720: z.string().optional(), - 1080: z.string().optional(), -}); - -/** Zod schema for landscape image size variants */ -const LandscapeSizesSchema = z.object({ - 640: z.string().optional(), - 960: z.string().optional(), - 1280: z.string().optional(), - 1920: z.string().optional(), - 2560: z.string().optional(), - 3840: z.string().optional(), -}); - -/** Zod schema for header image variants allowing explicit specification of responsive hero images */ -export const HeaderImageVariantsSchema = z.object({ - portrait: z - .object({ - avif: PortraitSizesSchema.optional(), - jpg: PortraitSizesSchema.optional(), - }) - .optional(), - landscape: z - .object({ - avif: LandscapeSizesSchema.optional(), - jpg: LandscapeSizesSchema.optional(), - }) - .optional(), -}); - -/** Zod schema for complete gallery data including metadata, sections, and sub-galleries */ -export const GalleryMetadataSchema = z.object({ - image: z.string().optional(), - imageWidth: z.number().optional(), - imageHeight: z.number().optional(), - ogUrl: z.string().optional(), - ogType: z.string().optional(), - ogSiteName: z.string().optional(), - twitterSite: z.string().optional(), - twitterCreator: z.string().optional(), - author: z.string().optional(), - keywords: z.string().optional(), - canonicalUrl: z.string().optional(), - language: z.string().optional(), - robots: z.string().optional(), -}); - -/** Zod schema for complete gallery data including metadata, sections, and sub-galleries */ -export const GalleryDataSchema = z.object({ - title: z.string(), - description: z.string(), - mediaBasePath: z.string().optional(), - url: z.string().optional(), - headerImage: z.string(), - headerImageBlurHash: z.string().optional(), - headerImageVariants: HeaderImageVariantsSchema.optional(), - thumbnailSize: z.number().optional(), - metadata: GalleryMetadataSchema, - mediaBaseUrl: z.string().optional(), - thumbsBaseUrl: z.string().optional(), - analyticsScript: z.string().optional(), - ctaBanner: z.boolean().optional(), - sections: z.array(GallerySectionSchema), - subGalleries: z.object({ title: z.string(), galleries: z.array(SubGallerySchema) }), -}); - -/** Zod schema for complete gallery data without mediaBasePath (deprecated) */ -export const GalleryDataDeprecatedSchema = z.object({ - title: z.string(), - description: z.string(), - url: z.string().optional(), - headerImage: z.string(), - thumbnailSize: z.number().optional(), - metadata: GalleryMetadataSchema, - mediaBaseUrl: z.string().optional(), - analyticsScript: z.string().optional(), - sections: z.array(GallerySectionDeprecatedSchema), - subGalleries: z.object({ title: z.string(), galleries: z.array(SubGallerySchema) }), -}); - -/** TypeScript type for thumbnail metadata */ -export type Thumbnail = z.infer; - -/** TypeScript type for media file metadata */ -export type MediaFile = z.infer; - -/** TypeScript type for gallery section data */ -export type GallerySection = z.infer; - -/** TypeScript type for sub-gallery metadata */ -export type SubGallery = z.infer; - -/** TypeScript type for header image variants */ -export type HeaderImageVariants = z.infer; - -/** TypeScript type for gallery metadata */ -export type GalleryMetadata = z.infer; - -/** TypeScript type for complete gallery data structure */ -export type GalleryData = z.infer; - -/** Deprecated types */ -export type MediaFileWithPath = z.infer; -export type GallerySectionDeprecated = z.infer; -export type GalleryDataDeprecated = z.infer; +export * from './gallery/index'; diff --git a/common/src/gallery/index.ts b/common/src/gallery/index.ts new file mode 100644 index 0000000..7b431f3 --- /dev/null +++ b/common/src/gallery/index.ts @@ -0,0 +1,25 @@ +export { + GalleryDataDeprecatedSchema, + GalleryDataSchema, + GalleryMetadataSchema, + GallerySectionDeprecatedSchema, + GallerySectionSchema, + HeaderImageVariantsSchema, + MediaFileDeprecatedSchema, + MediaFileSchema, + SubGallerySchema, + ThumbnailSchema, +} from './schemas'; + +export type { + GalleryData, + GalleryDataDeprecated, + GalleryMetadata, + GallerySection, + GallerySectionDeprecated, + HeaderImageVariants, + MediaFile, + MediaFileWithPath, + SubGallery, + Thumbnail, +} from './types'; diff --git a/common/src/gallery/schemas.ts b/common/src/gallery/schemas.ts new file mode 100644 index 0000000..955a34f --- /dev/null +++ b/common/src/gallery/schemas.ts @@ -0,0 +1,139 @@ +import { z } from 'zod'; + +/** Zod schema for thumbnail metadata including path and dimensions */ +export const ThumbnailSchema = z.object({ + baseUrl: z.string().optional(), + path: z.string(), + pathRetina: z.string(), + width: z.number(), + height: z.number(), + blurHash: z.string().optional(), +}); + +/** Zod schema for media file metadata including type, dimensions, and thumbnail info */ +export const MediaFileSchema = z.object({ + type: z.enum(['image', 'video']), + filename: z.string(), + url: z.string().optional(), + alt: z.string().optional(), + width: z.number(), + height: z.number(), + thumbnail: ThumbnailSchema.optional(), + lastMediaTimestamp: z.string().optional(), +}); + +/** Zod schema for media file with path (deprecated) */ +export const MediaFileDeprecatedSchema = z.object({ + type: z.enum(['image', 'video']), + path: z.string(), + alt: z.string().optional(), + width: z.number(), + height: z.number(), + thumbnail: ThumbnailSchema.optional(), + lastMediaTimestamp: z.string().optional(), +}); + +/** Zod schema for a gallery section containing title, description, and media files */ +export const GallerySectionSchema = z.object({ + title: z.string().optional(), + description: z.string().optional(), + images: z.array(MediaFileSchema), +}); + +/** Zod schema for a gallery section containing title, description, and media files (deprecated) */ +export const GallerySectionDeprecatedSchema = z.object({ + title: z.string().optional(), + description: z.string().optional(), + images: z.array(MediaFileDeprecatedSchema), +}); + +/** Zod schema for sub-gallery metadata including title, header image, and path */ +export const SubGallerySchema = z.object({ + title: z.string(), + headerImage: z.string(), + path: z.string(), +}); + +/** Zod schema for portrait image size variants */ +const PortraitSizesSchema = z.object({ + 360: z.string().optional(), + 480: z.string().optional(), + 720: z.string().optional(), + 1080: z.string().optional(), +}); + +/** Zod schema for landscape image size variants */ +const LandscapeSizesSchema = z.object({ + 640: z.string().optional(), + 960: z.string().optional(), + 1280: z.string().optional(), + 1920: z.string().optional(), + 2560: z.string().optional(), + 3840: z.string().optional(), +}); + +/** Zod schema for header image variants allowing explicit specification of responsive hero images */ +export const HeaderImageVariantsSchema = z.object({ + portrait: z + .object({ + avif: PortraitSizesSchema.optional(), + jpg: PortraitSizesSchema.optional(), + }) + .optional(), + landscape: z + .object({ + avif: LandscapeSizesSchema.optional(), + jpg: LandscapeSizesSchema.optional(), + }) + .optional(), +}); + +/** Zod schema for complete gallery data including metadata, sections, and sub-galleries */ +export const GalleryMetadataSchema = z.object({ + image: z.string().optional(), + imageWidth: z.number().optional(), + imageHeight: z.number().optional(), + ogUrl: z.string().optional(), + ogType: z.string().optional(), + ogSiteName: z.string().optional(), + twitterSite: z.string().optional(), + twitterCreator: z.string().optional(), + author: z.string().optional(), + keywords: z.string().optional(), + canonicalUrl: z.string().optional(), + language: z.string().optional(), + robots: z.string().optional(), +}); + +/** Zod schema for complete gallery data including metadata, sections, and sub-galleries */ +export const GalleryDataSchema = z.object({ + title: z.string(), + description: z.string(), + mediaBasePath: z.string().optional(), + url: z.string().optional(), + headerImage: z.string(), + headerImageBlurHash: z.string().optional(), + headerImageVariants: HeaderImageVariantsSchema.optional(), + thumbnailSize: z.number().optional(), + metadata: GalleryMetadataSchema, + mediaBaseUrl: z.string().optional(), + thumbsBaseUrl: z.string().optional(), + analyticsScript: z.string().optional(), + ctaBanner: z.boolean().optional(), + sections: z.array(GallerySectionSchema), + subGalleries: z.object({ title: z.string(), galleries: z.array(SubGallerySchema) }), +}); + +/** Zod schema for complete gallery data without mediaBasePath (deprecated) */ +export const GalleryDataDeprecatedSchema = z.object({ + title: z.string(), + description: z.string(), + url: z.string().optional(), + headerImage: z.string(), + thumbnailSize: z.number().optional(), + metadata: GalleryMetadataSchema, + mediaBaseUrl: z.string().optional(), + analyticsScript: z.string().optional(), + sections: z.array(GallerySectionDeprecatedSchema), + subGalleries: z.object({ title: z.string(), galleries: z.array(SubGallerySchema) }), +}); diff --git a/common/src/gallery/types.ts b/common/src/gallery/types.ts new file mode 100644 index 0000000..d607b01 --- /dev/null +++ b/common/src/gallery/types.ts @@ -0,0 +1,39 @@ +import type { + GalleryDataDeprecatedSchema, + GalleryDataSchema, + GalleryMetadataSchema, + GallerySectionDeprecatedSchema, + GallerySectionSchema, + HeaderImageVariantsSchema, + MediaFileDeprecatedSchema, + MediaFileSchema, + SubGallerySchema, + ThumbnailSchema, +} from './schemas'; +import type { z } from 'zod'; + +/** TypeScript type for thumbnail metadata */ +export type Thumbnail = z.infer; + +/** TypeScript type for media file metadata */ +export type MediaFile = z.infer; + +/** TypeScript type for gallery section data */ +export type GallerySection = z.infer; + +/** TypeScript type for sub-gallery metadata */ +export type SubGallery = z.infer; + +/** TypeScript type for header image variants */ +export type HeaderImageVariants = z.infer; + +/** TypeScript type for gallery metadata */ +export type GalleryMetadata = z.infer; + +/** TypeScript type for complete gallery data structure */ +export type GalleryData = z.infer; + +/** Deprecated types */ +export type MediaFileWithPath = z.infer; +export type GallerySectionDeprecated = z.infer; +export type GalleryDataDeprecated = z.infer; diff --git a/common/src/theme.ts b/common/src/theme.ts index 957e0bc..7143e6d 100644 --- a/common/src/theme.ts +++ b/common/src/theme.ts @@ -1,458 +1 @@ -import fs from 'node:fs'; -import path from 'node:path'; -import process from 'node:process'; - -import { marked } from 'marked'; - -import type { GalleryData, GalleryMetadata, GallerySection, HeaderImageVariants, MediaFile, SubGallery } from './gallery'; - -// ============================================================================ -// Types -// ============================================================================ - -/** Resolved hero data with all paths computed and markdown parsed */ -export 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 */ -export 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 */ -export interface ResolvedSection { - title?: string; - description?: string; - parsedDescription: string; - images: ResolvedImage[]; -} - -/** Resolved sub-gallery with computed thumbnail path */ -export interface ResolvedSubGallery { - title: string; - headerImage: string; - path: string; - thumbnailPath: string; -} - -/** Fully resolved gallery data ready for rendering */ -export interface ResolvedGalleryData { - title: string; - url?: string; - metadata: GalleryMetadata; - analyticsScript?: string; - ctaBanner?: boolean; - hero: ResolvedHero; - sections: ResolvedSection[]; - subGalleries?: { - title: string; - galleries: ResolvedSubGallery[]; - }; - // Pass through base URLs for components that need them - mediaBaseUrl?: string; - thumbsBaseUrl?: string; -} - -// ============================================================================ -// Constants -// ============================================================================ - -/** 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; - -// ============================================================================ -// Markdown Rendering -// ============================================================================ - -// Configure marked to only allow specific formatting options -const renderer = new marked.Renderer(); - -// Disable headings by rendering them as paragraphs -renderer.heading = ({ text }: { text: string }) => { - return '

' + text + '

\n'; -}; - -// Disable images -renderer.image = () => ''; - -// Disable HTML -renderer.html = () => ''; - -// Disable tables -renderer.table = () => ''; -renderer.tablerow = () => ''; -renderer.tablecell = () => ''; - -// Configure marked options -marked.use({ - renderer: renderer, - breaks: true, - gfm: true, -}); - -/** - * Renders markdown with limited formatting options. - * Supported: paragraphs, bold, italic, lists, code blocks, blockquotes, links - * Disabled: headings (rendered as paragraphs), images, HTML, tables - */ -export async function renderMarkdown(markdown: string): Promise { - if (!markdown) return ''; - return await marked.parse(markdown); -} - -// ============================================================================ -// Path Utilities -// ============================================================================ - -/** - * 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 - * @returns The normalized path relative to the gallery root directory - */ -export function getRelativePath(resourcePath: string): string { - const galleryConfigPath = path.resolve(process.env.GALLERY_JSON_PATH || ''); - const galleryConfigDir = path.dirname(galleryConfigPath); - - const absoluteResourcePath = path.resolve(path.join(galleryConfigDir, resourcePath)); - const baseDir = path.dirname(galleryConfigDir); - - return path.relative(baseDir, absoluteResourcePath); -} - -/** - * 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 - */ -export function getThumbnailPath(resourcePath: string, thumbsBaseUrl?: string, thumbnailBaseUrl?: string): string { - // If thumbnail-specific baseUrl is provided, use it and combine with the path - if (thumbnailBaseUrl) { - return `${thumbnailBaseUrl}/${resourcePath}`; - } - // Otherwise, use the gallery-level thumbsBaseUrl if provided - return thumbsBaseUrl ? `${thumbsBaseUrl}/${resourcePath}` : `gallery/images/${path.basename(resourcePath)}`; -} - -/** - * 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 - */ -export function getPhotoPath(filename: string, mediaBaseUrl?: string, url?: string): string { - // If url is provided, always use it regardless of base URL or path - if (url) { - return url; - } - - return mediaBaseUrl ? `${mediaBaseUrl}/${filename}` : filename; -} - -/** - * 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 - */ -export function getSubgalleryThumbnailPath(subgalleryHeaderImagePath: string): string { - const photoBasename = path.basename(subgalleryHeaderImagePath); - const subgalleryFolderName = path.basename(path.dirname(subgalleryHeaderImagePath)); - - return path.join(subgalleryFolderName, 'gallery', 'thumbnails', photoBasename); -} - -/** - * 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 function buildHeroSrcset( - variants: Record | 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(', '); -} - -// ============================================================================ -// Gallery Loading -// ============================================================================ - -/** - * Load gallery data from the GALLERY_JSON_PATH environment variable. - * - * @returns The parsed gallery data - * @throws Error if GALLERY_JSON_PATH is not set or file cannot be read - */ -export function loadGalleryData(): GalleryData { - const galleryJsonPath = process.env.GALLERY_JSON_PATH || './gallery.json'; - const galleryData = JSON.parse(fs.readFileSync(galleryJsonPath, 'utf8')); - return galleryData as GalleryData; -} - -// ============================================================================ -// Data Resolution -// ============================================================================ - -/** - * Resolve a single image with all paths computed. - */ -function resolveImage(image: MediaFile, mediaBaseUrl?: string, thumbsBaseUrl?: string): ResolvedImage { - const imagePath = getPhotoPath(image.filename, mediaBaseUrl, image.url); - const thumbnailPath = image.thumbnail - ? getThumbnailPath(image.thumbnail.path, thumbsBaseUrl, image.thumbnail.baseUrl) - : imagePath; - - const thumbnailSrcSet = image.thumbnail - ? getThumbnailPath(image.thumbnail.path, thumbsBaseUrl, image.thumbnail.baseUrl) + - ' 1x, ' + - getThumbnailPath(image.thumbnail.pathRetina, thumbsBaseUrl, image.thumbnail.baseUrl) + - ' 2x' - : undefined; - - return { - type: image.type, - filename: image.filename, - alt: image.alt, - width: image.width, - height: image.height, - imagePath, - thumbnailPath, - thumbnailSrcSet, - thumbnailWidth: image.thumbnail?.width, - thumbnailHeight: image.thumbnail?.height, - blurHash: image.thumbnail?.blurHash, - }; -} - -/** - * Resolve a section with parsed markdown and resolved image paths. - */ -async function resolveSection( - section: GallerySection, - mediaBaseUrl?: string, - thumbsBaseUrl?: string, -): Promise { - const parsedDescription = section.description ? await renderMarkdown(section.description) : ''; - - return { - title: section.title, - description: section.description, - parsedDescription, - images: section.images.map((img) => resolveImage(img, mediaBaseUrl, thumbsBaseUrl)), - }; -} - -/** - * Resolve a sub-gallery with computed thumbnail path. - */ -function resolveSubGallery(subGallery: SubGallery): ResolvedSubGallery { - return { - title: subGallery.title, - headerImage: subGallery.headerImage, - path: subGallery.path, - thumbnailPath: getSubgalleryThumbnailPath(subGallery.headerImage), - }; -} - -/** - * Resolve hero data with all paths computed and srcsets built. - */ -async function resolveHero(gallery: GalleryData): Promise { - const { title, description, headerImage, headerImageBlurHash, headerImageVariants, mediaBaseUrl, thumbsBaseUrl } = gallery; - - const parsedDescription = description ? await renderMarkdown(description) : ''; - const imgBasename = headerImage ? path.basename(headerImage, path.extname(headerImage)) : 'header'; - const thumbnailBasePath = thumbsBaseUrl || 'gallery/images'; - const headerPhotoPath = getPhotoPath(headerImage || '', mediaBaseUrl); - - // Determine which sources to show based on headerImageVariants - // If headerImageVariants is not set, use all generated paths (default behavior) - const useDefaultPaths = !headerImageVariants; - - const srcsets = { - portraitAvif: buildHeroSrcset( - headerImageVariants?.portrait?.avif, - PORTRAIT_SIZES, - thumbnailBasePath, - imgBasename, - 'portrait', - 'avif', - useDefaultPaths, - ), - portraitJpg: buildHeroSrcset( - headerImageVariants?.portrait?.jpg, - PORTRAIT_SIZES, - thumbnailBasePath, - imgBasename, - 'portrait', - 'jpg', - useDefaultPaths, - ), - landscapeAvif: buildHeroSrcset( - headerImageVariants?.landscape?.avif, - LANDSCAPE_SIZES, - thumbnailBasePath, - imgBasename, - 'landscape', - 'avif', - useDefaultPaths, - ), - landscapeJpg: buildHeroSrcset( - headerImageVariants?.landscape?.jpg, - LANDSCAPE_SIZES, - thumbnailBasePath, - imgBasename, - 'landscape', - 'jpg', - useDefaultPaths, - ), - }; - - return { - title, - description, - parsedDescription, - headerImage, - headerPhotoPath, - headerImageBlurHash, - headerImageVariants, - thumbnailBasePath, - imgBasename, - srcsets, - }; -} - -/** - * 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() - * @returns Fully resolved gallery data ready for rendering - */ -export async function resolveGalleryData(gallery: GalleryData): Promise { - const { mediaBaseUrl, thumbsBaseUrl, subGalleries } = gallery; - - const hero = await resolveHero(gallery); - const sections = await Promise.all( - gallery.sections.map((section) => resolveSection(section, mediaBaseUrl, thumbsBaseUrl)), - ); - - const resolvedSubGalleries = subGalleries?.galleries?.length - ? { - title: subGalleries.title, - galleries: subGalleries.galleries.map((sg) => resolveSubGallery(sg)), - } - : undefined; - - return { - title: gallery.title, - url: gallery.url, - metadata: gallery.metadata, - analyticsScript: gallery.analyticsScript, - ctaBanner: gallery.ctaBanner, - hero, - sections, - subGalleries: resolvedSubGalleries, - mediaBaseUrl, - thumbsBaseUrl, - }; -} - -// ============================================================================ -// Astro Integration -// ============================================================================ - -/** 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. - */ -export function preventEmptyContentFiles(): AstroIntegration { - return { - name: 'prevent-empty-content-files', - hooks: { - 'astro:build:done': ({ dir }) => { - const filesToRemove = ['content-assets.mjs', 'content-modules.mjs']; - for (const fileName of filesToRemove) { - const filePath = path.join(dir.pathname, fileName); - if (fs.existsSync(filePath)) { - try { - const content = fs.readFileSync(filePath, 'utf8'); - if (content.trim() === 'export default new Map();' || content.trim() === '') { - fs.unlinkSync(filePath); - } - } catch { - // Silently ignore errors - } - } - } - }, - }, - }; -} +export * from './theme/index'; diff --git a/common/src/theme/astro.ts b/common/src/theme/astro.ts new file mode 100644 index 0000000..81f6a6c --- /dev/null +++ b/common/src/theme/astro.ts @@ -0,0 +1,38 @@ +import fs from 'node:fs'; +import path from 'node:path'; + +/** 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. + */ +export function preventEmptyContentFiles(): AstroIntegration { + return { + name: 'prevent-empty-content-files', + hooks: { + 'astro:build:done': ({ dir }) => { + const filesToRemove = ['content-assets.mjs', 'content-modules.mjs']; + for (const fileName of filesToRemove) { + const filePath = path.join(dir.pathname, fileName); + if (fs.existsSync(filePath)) { + try { + const content = fs.readFileSync(filePath, 'utf8'); + if (content.trim() === 'export default new Map();' || content.trim() === '') { + fs.unlinkSync(filePath); + } + } catch { + // Silently ignore errors + } + } + } + }, + }, + }; +} diff --git a/common/src/theme/constants.ts b/common/src/theme/constants.ts new file mode 100644 index 0000000..b09409f --- /dev/null +++ b/common/src/theme/constants.ts @@ -0,0 +1,5 @@ +/** 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; diff --git a/common/src/theme/index.ts b/common/src/theme/index.ts new file mode 100644 index 0000000..1944a81 --- /dev/null +++ b/common/src/theme/index.ts @@ -0,0 +1,20 @@ +// Types +export type { ResolvedGalleryData, ResolvedHero, ResolvedImage, ResolvedSection, ResolvedSubGallery } from './types'; + +// Constants +export { LANDSCAPE_SIZES, PORTRAIT_SIZES } from './constants'; + +// Markdown +export { renderMarkdown } from './markdown'; + +// Path utilities +export { buildHeroSrcset, getPhotoPath, getRelativePath, getSubgalleryThumbnailPath, getThumbnailPath } from './paths'; + +// Gallery loading +export { loadGalleryData } from './loader'; + +// Data resolution +export { resolveGalleryData } from './resolver'; + +// Astro integration +export { preventEmptyContentFiles } from './astro'; diff --git a/common/src/theme/loader.ts b/common/src/theme/loader.ts new file mode 100644 index 0000000..33e07a3 --- /dev/null +++ b/common/src/theme/loader.ts @@ -0,0 +1,16 @@ +import fs from 'node:fs'; +import process from 'node:process'; + +import type { GalleryData } from '../gallery'; + +/** + * Load gallery data from the GALLERY_JSON_PATH environment variable. + * + * @returns The parsed gallery data + * @throws Error if GALLERY_JSON_PATH is not set or file cannot be read + */ +export function loadGalleryData(): GalleryData { + const galleryJsonPath = process.env.GALLERY_JSON_PATH || './gallery.json'; + const galleryData = JSON.parse(fs.readFileSync(galleryJsonPath, 'utf8')); + return galleryData as GalleryData; +} diff --git a/common/src/theme/markdown.ts b/common/src/theme/markdown.ts new file mode 100644 index 0000000..36ff431 --- /dev/null +++ b/common/src/theme/markdown.ts @@ -0,0 +1,37 @@ +import { marked } from 'marked'; + +// Configure marked to only allow specific formatting options +const renderer = new marked.Renderer(); + +// Disable headings by rendering them as paragraphs +renderer.heading = ({ text }: { text: string }) => { + return '

' + text + '

\n'; +}; + +// Disable images +renderer.image = () => ''; + +// Disable HTML +renderer.html = () => ''; + +// Disable tables +renderer.table = () => ''; +renderer.tablerow = () => ''; +renderer.tablecell = () => ''; + +// Configure marked options +marked.use({ + renderer: renderer, + breaks: true, + gfm: true, +}); + +/** + * Renders markdown with limited formatting options. + * Supported: paragraphs, bold, italic, lists, code blocks, blockquotes, links + * Disabled: headings (rendered as paragraphs), images, HTML, tables + */ +export async function renderMarkdown(markdown: string): Promise { + if (!markdown) return ''; + return await marked.parse(markdown); +} diff --git a/common/src/theme/paths.ts b/common/src/theme/paths.ts new file mode 100644 index 0000000..9315268 --- /dev/null +++ b/common/src/theme/paths.ts @@ -0,0 +1,102 @@ +import path from 'node:path'; +import process from 'node:process'; + +/** + * 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 + * @returns The normalized path relative to the gallery root directory + */ +export function getRelativePath(resourcePath: string): string { + const galleryConfigPath = path.resolve(process.env.GALLERY_JSON_PATH || ''); + const galleryConfigDir = path.dirname(galleryConfigPath); + + const absoluteResourcePath = path.resolve(path.join(galleryConfigDir, resourcePath)); + const baseDir = path.dirname(galleryConfigDir); + + return path.relative(baseDir, absoluteResourcePath); +} + +/** + * 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 + */ +export function getThumbnailPath(resourcePath: string, thumbsBaseUrl?: string, thumbnailBaseUrl?: string): string { + // If thumbnail-specific baseUrl is provided, use it and combine with the path + if (thumbnailBaseUrl) { + return `${thumbnailBaseUrl}/${resourcePath}`; + } + // Otherwise, use the gallery-level thumbsBaseUrl if provided + return thumbsBaseUrl ? `${thumbsBaseUrl}/${resourcePath}` : `gallery/images/${path.basename(resourcePath)}`; +} + +/** + * 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 + */ +export function getPhotoPath(filename: string, mediaBaseUrl?: string, url?: string): string { + // If url is provided, always use it regardless of base URL or path + if (url) { + return url; + } + + return mediaBaseUrl ? `${mediaBaseUrl}/${filename}` : filename; +} + +/** + * 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 + */ +export function getSubgalleryThumbnailPath(subgalleryHeaderImagePath: string): string { + const photoBasename = path.basename(subgalleryHeaderImagePath); + const subgalleryFolderName = path.basename(path.dirname(subgalleryHeaderImagePath)); + + return path.join(subgalleryFolderName, 'gallery', 'thumbnails', photoBasename); +} + +/** + * 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 function buildHeroSrcset( + variants: Record | 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(', '); +} diff --git a/common/src/theme/resolver.ts b/common/src/theme/resolver.ts new file mode 100644 index 0000000..85628f0 --- /dev/null +++ b/common/src/theme/resolver.ts @@ -0,0 +1,173 @@ +import path from 'node:path'; + +import { LANDSCAPE_SIZES, PORTRAIT_SIZES } from './constants'; +import { renderMarkdown } from './markdown'; +import { buildHeroSrcset, getPhotoPath, getSubgalleryThumbnailPath, getThumbnailPath } from './paths'; + +import type { GalleryData, GallerySection, MediaFile, SubGallery } from '../gallery'; +import type { ResolvedGalleryData, ResolvedHero, ResolvedImage, ResolvedSection, ResolvedSubGallery } from './types'; + +/** + * Resolve a single image with all paths computed. + */ +function resolveImage(image: MediaFile, mediaBaseUrl?: string, thumbsBaseUrl?: string): ResolvedImage { + const imagePath = getPhotoPath(image.filename, mediaBaseUrl, image.url); + const thumbnailPath = image.thumbnail + ? getThumbnailPath(image.thumbnail.path, thumbsBaseUrl, image.thumbnail.baseUrl) + : imagePath; + + const thumbnailSrcSet = image.thumbnail + ? getThumbnailPath(image.thumbnail.path, thumbsBaseUrl, image.thumbnail.baseUrl) + + ' 1x, ' + + getThumbnailPath(image.thumbnail.pathRetina, thumbsBaseUrl, image.thumbnail.baseUrl) + + ' 2x' + : undefined; + + return { + type: image.type, + filename: image.filename, + alt: image.alt, + width: image.width, + height: image.height, + imagePath, + thumbnailPath, + thumbnailSrcSet, + thumbnailWidth: image.thumbnail?.width, + thumbnailHeight: image.thumbnail?.height, + blurHash: image.thumbnail?.blurHash, + }; +} + +/** + * Resolve a section with parsed markdown and resolved image paths. + */ +async function resolveSection( + section: GallerySection, + mediaBaseUrl?: string, + thumbsBaseUrl?: string, +): Promise { + const parsedDescription = section.description ? await renderMarkdown(section.description) : ''; + + return { + title: section.title, + description: section.description, + parsedDescription, + images: section.images.map((img) => resolveImage(img, mediaBaseUrl, thumbsBaseUrl)), + }; +} + +/** + * Resolve a sub-gallery with computed thumbnail path. + */ +function resolveSubGallery(subGallery: SubGallery): ResolvedSubGallery { + return { + title: subGallery.title, + headerImage: subGallery.headerImage, + path: subGallery.path, + thumbnailPath: getSubgalleryThumbnailPath(subGallery.headerImage), + }; +} + +/** + * Resolve hero data with all paths computed and srcsets built. + */ +async function resolveHero(gallery: GalleryData): Promise { + const { title, description, headerImage, headerImageBlurHash, headerImageVariants, mediaBaseUrl, thumbsBaseUrl } = gallery; + + const parsedDescription = description ? await renderMarkdown(description) : ''; + const imgBasename = headerImage ? path.basename(headerImage, path.extname(headerImage)) : 'header'; + const thumbnailBasePath = thumbsBaseUrl || 'gallery/images'; + const headerPhotoPath = getPhotoPath(headerImage || '', mediaBaseUrl); + + // Determine which sources to show based on headerImageVariants + // If headerImageVariants is not set, use all generated paths (default behavior) + const useDefaultPaths = !headerImageVariants; + + const srcsets = { + portraitAvif: buildHeroSrcset( + headerImageVariants?.portrait?.avif, + PORTRAIT_SIZES, + thumbnailBasePath, + imgBasename, + 'portrait', + 'avif', + useDefaultPaths, + ), + portraitJpg: buildHeroSrcset( + headerImageVariants?.portrait?.jpg, + PORTRAIT_SIZES, + thumbnailBasePath, + imgBasename, + 'portrait', + 'jpg', + useDefaultPaths, + ), + landscapeAvif: buildHeroSrcset( + headerImageVariants?.landscape?.avif, + LANDSCAPE_SIZES, + thumbnailBasePath, + imgBasename, + 'landscape', + 'avif', + useDefaultPaths, + ), + landscapeJpg: buildHeroSrcset( + headerImageVariants?.landscape?.jpg, + LANDSCAPE_SIZES, + thumbnailBasePath, + imgBasename, + 'landscape', + 'jpg', + useDefaultPaths, + ), + }; + + return { + title, + description, + parsedDescription, + headerImage, + headerPhotoPath, + headerImageBlurHash, + headerImageVariants, + thumbnailBasePath, + imgBasename, + srcsets, + }; +} + +/** + * 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() + * @returns Fully resolved gallery data ready for rendering + */ +export async function resolveGalleryData(gallery: GalleryData): Promise { + const { mediaBaseUrl, thumbsBaseUrl, subGalleries } = gallery; + + const hero = await resolveHero(gallery); + const sections = await Promise.all( + gallery.sections.map((section) => resolveSection(section, mediaBaseUrl, thumbsBaseUrl)), + ); + + const resolvedSubGalleries = subGalleries?.galleries?.length + ? { + title: subGalleries.title, + galleries: subGalleries.galleries.map((sg) => resolveSubGallery(sg)), + } + : undefined; + + return { + title: gallery.title, + url: gallery.url, + metadata: gallery.metadata, + analyticsScript: gallery.analyticsScript, + ctaBanner: gallery.ctaBanner, + hero, + sections, + subGalleries: resolvedSubGalleries, + mediaBaseUrl, + thumbsBaseUrl, + }; +} diff --git a/common/src/theme/types.ts b/common/src/theme/types.ts new file mode 100644 index 0000000..9fbd313 --- /dev/null +++ b/common/src/theme/types.ts @@ -0,0 +1,69 @@ +import type { GalleryMetadata, HeaderImageVariants } from '../gallery'; + +/** Resolved hero data with all paths computed and markdown parsed */ +export 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 */ +export 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 */ +export interface ResolvedSection { + title?: string; + description?: string; + parsedDescription: string; + images: ResolvedImage[]; +} + +/** Resolved sub-gallery with computed thumbnail path */ +export interface ResolvedSubGallery { + title: string; + headerImage: string; + path: string; + thumbnailPath: string; +} + +/** Fully resolved gallery data ready for rendering */ +export interface ResolvedGalleryData { + title: string; + url?: string; + metadata: GalleryMetadata; + analyticsScript?: string; + ctaBanner?: boolean; + hero: ResolvedHero; + sections: ResolvedSection[]; + subGalleries?: { + title: string; + galleries: ResolvedSubGallery[]; + }; + // Pass through base URLs for components that need them + mediaBaseUrl?: string; + thumbsBaseUrl?: string; +} From b345eb48d1b456ce4c74983b29e7aa57595410a9 Mon Sep 17 00:00:00 2001 From: rustoma Date: Thu, 22 Jan 2026 19:43:13 +0100 Subject: [PATCH 35/55] feat: add CSS utility functions for color manipulation and theming support --- common/src/client/css-utils.ts | 71 +++++++++++++++++++ common/src/client/index.ts | 3 + common/src/client/photoswipe/lightbox.ts | 8 +-- common/src/gallery/schemas.ts | 15 +++- common/src/gallery/types.ts | 15 +++- common/src/theme/index.ts | 1 + common/src/theme/loader.ts | 9 ++- common/src/theme/paths.ts | 6 +- common/src/theme/resolver.ts | 27 +++++-- common/src/theme/types.ts | 2 + .../templates/base/src/pages/index.astro | 5 +- .../sub-galleries/SubGalleries.astro | 4 +- .../themes/base-theme/pages/index.astro | 5 +- .../themes/base-theme/utils/queryParams.ts | 57 +-------------- 14 files changed, 146 insertions(+), 82 deletions(-) create mode 100644 common/src/client/css-utils.ts diff --git a/common/src/client/css-utils.ts b/common/src/client/css-utils.ts new file mode 100644 index 0000000..d249379 --- /dev/null +++ b/common/src/client/css-utils.ts @@ -0,0 +1,71 @@ +/** + * CSS utility functions for client-side theming and color manipulation. + * These utilities are browser-only and require DOM access. + */ + +/** + * Normalizes hex color values to 6-digit format (e.g., #abc -> #aabbcc). + * Returns null if the hex value is invalid. + * + * @param hex - The hex color value to normalize (with or without #) + * @returns The normalized 6-digit hex color with # prefix, or null if invalid + */ +export function normalizeHex(hex: string): string | null { + hex = hex.replace('#', ''); + if (hex.length === 3) hex = [...hex].map((c) => c + c).join(''); + return hex.length === 6 && /^[0-9A-Fa-f]{6}$/.test(hex) ? `#${hex}` : null; +} + +/** + * Parses and validates a color value. + * Supports CSS color names, hex values, rgb/rgba, and 'transparent'. + * Returns null if the color is invalid. + * + * @param colorParam - The color string to parse + * @returns The validated color string, or null if invalid + */ +export function parseColor(colorParam: string | null): string | null { + if (!colorParam) return null; + const normalized = colorParam.toLowerCase().trim(); + if (normalized === 'transparent') return 'transparent'; + + const testEl = document.createElement('div'); + testEl.style.color = normalized; + if (testEl.style.color) return normalized; + + return normalizeHex(colorParam); +} + +/** + * Sets or removes a CSS custom property (variable) on an element. + * Removes the property if value is null. + * + * @param element - The HTML element to modify + * @param name - The CSS variable name (e.g., '--my-color') + * @param value - The value to set, or null to remove + */ +export function setCSSVar(element: HTMLElement, name: string, value: string | null): void { + if (value) { + element.style.setProperty(name, value); + } else { + element.style.removeProperty(name); + } +} + +/** + * Derives a color with adjusted opacity from an existing color. + * Converts rgb to rgba if needed, or adjusts existing rgba opacity. + * + * @param color - The source color (rgb, rgba, or other CSS color) + * @param opacity - The target opacity (0-1) + * @returns The color with adjusted opacity, or original if not rgb/rgba + */ +export function deriveOpacityColor(color: string, opacity: number): string { + if (color.startsWith('rgba')) { + return color.replace(/,\s*[\d.]+\)$/, `, ${opacity})`); + } + if (color.startsWith('rgb')) { + return color.replace('rgb', 'rgba').replace(')', `, ${opacity})`); + } + return color; +} diff --git a/common/src/client/index.ts b/common/src/client/index.ts index 4170831..2067f23 100644 --- a/common/src/client/index.ts +++ b/common/src/client/index.ts @@ -8,3 +8,6 @@ export { initHeroImageFallback } from './hero-fallback'; // PhotoSwipe integration export type { GalleryLightboxOptions, VideoPluginOptions } from './photoswipe'; export { createGalleryLightbox, injectPhotoSwipeStyles, PhotoSwipeVideoPlugin } from './photoswipe'; + +// CSS utilities +export { deriveOpacityColor, normalizeHex, parseColor, setCSSVar } from './css-utils'; diff --git a/common/src/client/photoswipe/lightbox.ts b/common/src/client/photoswipe/lightbox.ts index 01862b7..674b9fc 100644 --- a/common/src/client/photoswipe/lightbox.ts +++ b/common/src/client/photoswipe/lightbox.ts @@ -1,10 +1,10 @@ -import type PhotoSwipe from 'photoswipe'; -import type PhotoSwipeLightbox from 'photoswipe/lightbox'; - import { injectPhotoSwipeStyles } from './styles'; -import type { VideoPluginOptions } from './types'; import { PhotoSwipeVideoPlugin } from './video-plugin'; +import type { VideoPluginOptions } from './types'; +import type PhotoSwipe from 'photoswipe'; +import type PhotoSwipeLightbox from 'photoswipe/lightbox'; + /** Options for creating a gallery lightbox */ export interface GalleryLightboxOptions { /** CSS selector for gallery container (default: '.gallery-grid') */ diff --git a/common/src/gallery/schemas.ts b/common/src/gallery/schemas.ts index 955a34f..246e054 100644 --- a/common/src/gallery/schemas.ts +++ b/common/src/gallery/schemas.ts @@ -22,7 +22,10 @@ export const MediaFileSchema = z.object({ lastMediaTimestamp: z.string().optional(), }); -/** Zod schema for media file with path (deprecated) */ +/** + * Zod schema for media file with path. + * @deprecated Use MediaFileSchema instead which uses 'filename' instead of 'path'. + */ export const MediaFileDeprecatedSchema = z.object({ type: z.enum(['image', 'video']), path: z.string(), @@ -40,7 +43,10 @@ export const GallerySectionSchema = z.object({ images: z.array(MediaFileSchema), }); -/** Zod schema for a gallery section containing title, description, and media files (deprecated) */ +/** + * Zod schema for a gallery section containing title, description, and media files. + * @deprecated Use GallerySectionSchema instead which uses MediaFileSchema. + */ export const GallerySectionDeprecatedSchema = z.object({ title: z.string().optional(), description: z.string().optional(), @@ -124,7 +130,10 @@ export const GalleryDataSchema = z.object({ subGalleries: z.object({ title: z.string(), galleries: z.array(SubGallerySchema) }), }); -/** Zod schema for complete gallery data without mediaBasePath (deprecated) */ +/** + * Zod schema for complete gallery data without mediaBasePath. + * @deprecated Use GalleryDataSchema instead which includes mediaBasePath and headerImageVariants. + */ export const GalleryDataDeprecatedSchema = z.object({ title: z.string(), description: z.string(), diff --git a/common/src/gallery/types.ts b/common/src/gallery/types.ts index d607b01..010c81e 100644 --- a/common/src/gallery/types.ts +++ b/common/src/gallery/types.ts @@ -33,7 +33,20 @@ export type GalleryMetadata = z.infer; /** TypeScript type for complete gallery data structure */ export type GalleryData = z.infer; -/** Deprecated types */ +/** + * TypeScript type for media file with path. + * @deprecated Use MediaFile instead which uses 'filename' instead of 'path'. + */ export type MediaFileWithPath = z.infer; + +/** + * TypeScript type for gallery section with deprecated media file format. + * @deprecated Use GallerySection instead which uses MediaFile. + */ export type GallerySectionDeprecated = z.infer; + +/** + * TypeScript type for complete gallery data without mediaBasePath. + * @deprecated Use GalleryData instead which includes mediaBasePath and headerImageVariants. + */ export type GalleryDataDeprecated = z.infer; diff --git a/common/src/theme/index.ts b/common/src/theme/index.ts index 1944a81..ec0a00f 100644 --- a/common/src/theme/index.ts +++ b/common/src/theme/index.ts @@ -14,6 +14,7 @@ export { buildHeroSrcset, getPhotoPath, getRelativePath, getSubgalleryThumbnailP export { loadGalleryData } from './loader'; // Data resolution +export type { ResolveGalleryDataOptions } from './resolver'; export { resolveGalleryData } from './resolver'; // Astro integration diff --git a/common/src/theme/loader.ts b/common/src/theme/loader.ts index 33e07a3..8fe605e 100644 --- a/common/src/theme/loader.ts +++ b/common/src/theme/loader.ts @@ -1,16 +1,15 @@ import fs from 'node:fs'; -import process from 'node:process'; import type { GalleryData } from '../gallery'; /** - * Load gallery data from the GALLERY_JSON_PATH environment variable. + * Load gallery data from a JSON file. * + * @param galleryJsonPath - Path to the gallery.json file. Defaults to './gallery.json'. * @returns The parsed gallery data - * @throws Error if GALLERY_JSON_PATH is not set or file cannot be read + * @throws Error if file cannot be read or parsed */ -export function loadGalleryData(): GalleryData { - const galleryJsonPath = process.env.GALLERY_JSON_PATH || './gallery.json'; +export function loadGalleryData(galleryJsonPath = './gallery.json'): GalleryData { const galleryData = JSON.parse(fs.readFileSync(galleryJsonPath, 'utf8')); return galleryData as GalleryData; } diff --git a/common/src/theme/paths.ts b/common/src/theme/paths.ts index 9315268..338399d 100644 --- a/common/src/theme/paths.ts +++ b/common/src/theme/paths.ts @@ -1,14 +1,14 @@ import path from 'node:path'; -import process from 'node:process'; /** * 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 */ -export function getRelativePath(resourcePath: string): string { - const galleryConfigPath = path.resolve(process.env.GALLERY_JSON_PATH || ''); +export function getRelativePath(resourcePath: string, galleryJsonPath: string): string { + const galleryConfigPath = path.resolve(galleryJsonPath); const galleryConfigDir = path.dirname(galleryConfigPath); const absoluteResourcePath = path.resolve(path.join(galleryConfigDir, resourcePath)); diff --git a/common/src/theme/resolver.ts b/common/src/theme/resolver.ts index 85628f0..815b781 100644 --- a/common/src/theme/resolver.ts +++ b/common/src/theme/resolver.ts @@ -2,7 +2,7 @@ import path from 'node:path'; import { LANDSCAPE_SIZES, PORTRAIT_SIZES } from './constants'; import { renderMarkdown } from './markdown'; -import { buildHeroSrcset, getPhotoPath, getSubgalleryThumbnailPath, getThumbnailPath } from './paths'; +import { buildHeroSrcset, getPhotoPath, getRelativePath, getSubgalleryThumbnailPath, getThumbnailPath } from './paths'; import type { GalleryData, GallerySection, MediaFile, SubGallery } from '../gallery'; import type { ResolvedGalleryData, ResolvedHero, ResolvedImage, ResolvedSection, ResolvedSubGallery } from './types'; @@ -57,14 +57,15 @@ async function resolveSection( } /** - * Resolve a sub-gallery with computed thumbnail path. + * Resolve a sub-gallery with computed thumbnail path and optional resolved path. */ -function resolveSubGallery(subGallery: SubGallery): ResolvedSubGallery { +function resolveSubGallery(subGallery: SubGallery, galleryJsonPath?: string): ResolvedSubGallery { return { title: subGallery.title, headerImage: subGallery.headerImage, path: subGallery.path, thumbnailPath: getSubgalleryThumbnailPath(subGallery.headerImage), + resolvedPath: galleryJsonPath ? getRelativePath(subGallery.path, galleryJsonPath) : undefined, }; } @@ -136,15 +137,31 @@ async function resolveHero(gallery: GalleryData): Promise { }; } +/** + * Options for resolving gallery data. + */ +export interface ResolveGalleryDataOptions { + /** + * Path to the gallery.json file. When provided, enables resolution of + * relative paths for sub-galleries (resolvedPath field). + */ + galleryJsonPath?: string; +} + /** * 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 */ -export async function resolveGalleryData(gallery: GalleryData): Promise { +export async function resolveGalleryData( + gallery: GalleryData, + options?: ResolveGalleryDataOptions, +): Promise { const { mediaBaseUrl, thumbsBaseUrl, subGalleries } = gallery; + const { galleryJsonPath } = options ?? {}; const hero = await resolveHero(gallery); const sections = await Promise.all( @@ -154,7 +171,7 @@ export async function resolveGalleryData(gallery: GalleryData): Promise resolveSubGallery(sg)), + galleries: subGalleries.galleries.map((sg) => resolveSubGallery(sg, galleryJsonPath)), } : undefined; diff --git a/common/src/theme/types.ts b/common/src/theme/types.ts index 9fbd313..e827fc9 100644 --- a/common/src/theme/types.ts +++ b/common/src/theme/types.ts @@ -48,6 +48,8 @@ export interface ResolvedSubGallery { 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 */ diff --git a/gallery/src/modules/create-theme/templates/base/src/pages/index.astro b/gallery/src/modules/create-theme/templates/base/src/pages/index.astro index f19b608..2659c68 100644 --- a/gallery/src/modules/create-theme/templates/base/src/pages/index.astro +++ b/gallery/src/modules/create-theme/templates/base/src/pages/index.astro @@ -5,8 +5,9 @@ import Hero from '@/components/Hero.astro'; import MainLayout from '@/layouts/MainLayout.astro'; // Load and resolve gallery data - all paths are pre-computed -const raw = loadGalleryData(); -const gallery = await resolveGalleryData(raw); +const galleryJsonPath = import.meta.env.GALLERY_JSON_PATH || './gallery.json'; +const raw = loadGalleryData(galleryJsonPath); +const gallery = await resolveGalleryData(raw, { galleryJsonPath }); --- { subGalleries.map((subgallery) => ( - +
{subgallery.title}
diff --git a/themes/modern/src/features/themes/base-theme/pages/index.astro b/themes/modern/src/features/themes/base-theme/pages/index.astro index 43ab722..98a9818 100644 --- a/themes/modern/src/features/themes/base-theme/pages/index.astro +++ b/themes/modern/src/features/themes/base-theme/pages/index.astro @@ -10,8 +10,9 @@ import SubGalleries from '@/features/themes/base-theme/components/sub-galleries/ import MainLayout from '@/features/themes/base-theme/layouts/MainLayout.astro'; // Load and resolve gallery data - all paths are pre-computed -const raw = loadGalleryData(); -const gallery = await resolveGalleryData(raw); +const galleryJsonPath = import.meta.env.GALLERY_JSON_PATH || './gallery.json'; +const raw = loadGalleryData(galleryJsonPath); +const gallery = await resolveGalleryData(raw, { galleryJsonPath }); const showCtaBanner = gallery.ctaBanner === true; --- diff --git a/themes/modern/src/features/themes/base-theme/utils/queryParams.ts b/themes/modern/src/features/themes/base-theme/utils/queryParams.ts index f9a5ef6..48222c4 100644 --- a/themes/modern/src/features/themes/base-theme/utils/queryParams.ts +++ b/themes/modern/src/features/themes/base-theme/utils/queryParams.ts @@ -1,3 +1,5 @@ +import { deriveOpacityColor, parseColor, setCSSVar } from '@simple-photo-gallery/common/client'; + const TYPOGRAPHY_MODERN_THEME_PRESETS: Record = { light: { title: 'rgba(255, 255, 255, 0.95)', description: 'rgba(255, 255, 255, 0.75)' }, white: { title: 'rgba(255, 255, 255, 0.95)', description: 'rgba(255, 255, 255, 0.75)' }, @@ -5,59 +7,6 @@ const TYPOGRAPHY_MODERN_THEME_PRESETS: Record #aabbcc). - * Returns null if the hex value is invalid. - */ -const normalizeHex = (hex: string): string | null => { - hex = hex.replace('#', ''); - if (hex.length === 3) hex = [...hex].map((c) => c + c).join(''); - return hex.length === 6 && /^[0-9A-Fa-f]{6}$/.test(hex) ? `#${hex}` : null; -}; - -/** - * Parses and validates a color value from query parameters. - * Supports CSS color names, hex values, rgb/rgba, and 'transparent'. - * Returns null if the color is invalid. - */ -const parseColor = (colorParam: string | null): string | null => { - if (!colorParam) return null; - const normalized = colorParam.toLowerCase().trim(); - if (normalized === 'transparent') return 'transparent'; - - const testEl = document.createElement('div'); - testEl.style.color = normalized; - if (testEl.style.color) return normalized; - - return normalizeHex(colorParam); -}; - -/** - * Sets or removes a CSS custom property (variable) on an element. - * Removes the property if value is null. - */ -const setCSSVar = (root: HTMLElement, name: string, value: string | null): void => { - if (value) { - root.style.setProperty(name, value); - } else { - root.style.removeProperty(name); - } -}; - -/** - * Derives a description color from a title color by adjusting opacity to 0.8. - * Converts rgb to rgba if needed, otherwise returns the original color. - */ -const deriveDescriptionColor = (titleColor: string): string => { - if (titleColor.startsWith('rgba')) { - return titleColor.replace(/,\s*[\d.]+\)$/, ', 0.8)'); - } - if (titleColor.startsWith('rgb')) { - return titleColor.replace('rgb', 'rgba').replace(')', ', 0.8)'); - } - return titleColor; -}; - /** * Controls the visibility of the hero/header image based on the 'headerImage' query parameter. * Hides the hero section if headerImage is 'false' or '0'. @@ -116,7 +65,7 @@ const applyTypographyColors = (params: URLSearchParams): void => { const color = parseColor(typographyParam); if (color) { setCSSVar(root, '--typography-color-title', color); - setCSSVar(root, '--typography-color-description', deriveDescriptionColor(color)); + setCSSVar(root, '--typography-color-description', deriveOpacityColor(color, 0.8)); } else { setCSSVar(root, '--typography-color-title', null); setCSSVar(root, '--typography-color-description', null); From f7dafdcb5150187003eeac6c69b827345b94caaa Mon Sep 17 00:00:00 2001 From: rustoma Date: Thu, 22 Jan 2026 19:53:35 +0100 Subject: [PATCH 36/55] feat: introduce CSS custom properties for PhotoSwipe customization and update imports --- common/src/client/index.ts | 2 +- common/src/client/photoswipe/index.ts | 2 +- common/src/client/photoswipe/styles.ts | 146 +++++++++++++++++++++---- 3 files changed, 125 insertions(+), 25 deletions(-) diff --git a/common/src/client/index.ts b/common/src/client/index.ts index 2067f23..0af37e4 100644 --- a/common/src/client/index.ts +++ b/common/src/client/index.ts @@ -7,7 +7,7 @@ export { initHeroImageFallback } from './hero-fallback'; // PhotoSwipe integration export type { GalleryLightboxOptions, VideoPluginOptions } from './photoswipe'; -export { createGalleryLightbox, injectPhotoSwipeStyles, PhotoSwipeVideoPlugin } from './photoswipe'; +export { createGalleryLightbox, injectPhotoSwipeStyles, PHOTOSWIPE_CSS_VARS, PhotoSwipeVideoPlugin } from './photoswipe'; // CSS utilities export { deriveOpacityColor, normalizeHex, parseColor, setCSSVar } from './css-utils'; diff --git a/common/src/client/photoswipe/index.ts b/common/src/client/photoswipe/index.ts index 9cc7da4..e60516d 100644 --- a/common/src/client/photoswipe/index.ts +++ b/common/src/client/photoswipe/index.ts @@ -1,5 +1,5 @@ export type { GalleryLightboxOptions } from './lightbox'; export { createGalleryLightbox } from './lightbox'; -export { injectPhotoSwipeStyles } from './styles'; +export { injectPhotoSwipeStyles, PHOTOSWIPE_CSS_VARS } from './styles'; export type { VideoPluginOptions } from './types'; export { PhotoSwipeVideoPlugin } from './video-plugin'; diff --git a/common/src/client/photoswipe/styles.ts b/common/src/client/photoswipe/styles.ts index de8554a..3379ce2 100644 --- a/common/src/client/photoswipe/styles.ts +++ b/common/src/client/photoswipe/styles.ts @@ -1,22 +1,110 @@ +/** + * Available CSS custom properties for PhotoSwipe customization. + * Themes can override these variables in their own stylesheets. + * + * @example + * ```css + * :root { + * --pswp-caption-bg: rgba(0, 20, 40, 0.9); + * --pswp-caption-radius: 8px; + * --pswp-button-color: #3b82f6; + * } + * ``` + */ +export const PHOTOSWIPE_CSS_VARS = { + // Background + bgColor: '--pswp-bg-color', + + // Buttons + buttonColor: '--pswp-button-color', + buttonOpacity: '--pswp-button-opacity', + buttonOpacityHover: '--pswp-button-opacity-hover', + + // Counter + counterColor: '--pswp-counter-color', + counterFontSize: '--pswp-counter-font-size', + + // Caption container + captionBg: '--pswp-caption-bg', + captionBlur: '--pswp-caption-blur', + captionColor: '--pswp-caption-color', + captionPadding: '--pswp-caption-padding', + captionPaddingMobile: '--pswp-caption-padding-mobile', + captionRadius: '--pswp-caption-radius', + captionMargin: '--pswp-caption-margin', + captionMarginMobile: '--pswp-caption-margin-mobile', + captionShadow: '--pswp-caption-shadow', + captionMaxWidth: '--pswp-caption-max-width', + + // Caption typography + captionTitleSize: '--pswp-caption-title-size', + captionTitleWeight: '--pswp-caption-title-weight', + captionTextSize: '--pswp-caption-text-size', + captionTextSizeMobile: '--pswp-caption-text-size-mobile', + captionDescriptionSize: '--pswp-caption-description-size', + + // Animation + slideAnimationDuration: '--pswp-slide-animation-duration', + slideAnimationEasing: '--pswp-slide-animation-easing', +} as const; + const PHOTOSWIPE_STYLES = ` +/* 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: rgba(0, 0, 0, 1); + --pswp-bg: var(--pswp-bg-color); } .pswp__counter { - color: white; - font-size: 1rem; + color: var(--pswp-counter-color); + font-size: var(--pswp-counter-font-size); } .pswp__button { - color: white; - opacity: 0.8; + color: var(--pswp-button-color); + opacity: var(--pswp-button-opacity); transition: opacity 0.3s ease; } .pswp__button:hover { - opacity: 1; + opacity: var(--pswp-button-opacity-hover); } .pswp__caption { @@ -34,39 +122,39 @@ const PHOTOSWIPE_STYLES = ` .pswp__caption .image-caption { text-align: left; - background: rgba(128, 128, 128, 0.3); - backdrop-filter: blur(8px); - -webkit-backdrop-filter: blur(8px); - color: white; - padding: 16px; - border-radius: 16px; - margin: 1rem; - box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3); + 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: 8px 16px; - font-size: 0.8rem; - margin: 8px 0; + 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: 42rem; + max-width: var(--pswp-caption-max-width); margin: 0 auto; } .pswp__caption h3 { - font-size: 1.5rem; - font-weight: 600; + 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: 1rem; + 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); @@ -76,7 +164,7 @@ const PHOTOSWIPE_STYLES = ` .pswp__caption .description { display: block; margin-top: 0.5rem; - font-size: 0.95rem; + font-size: var(--pswp-caption-description-size); opacity: 0.9; font-weight: 300; font-style: italic; @@ -88,7 +176,7 @@ const PHOTOSWIPE_STYLES = ` } .pswp__img--in-viewport { - animation: pswp-slideIn 0.6s ease-out forwards; + animation: pswp-slideIn var(--pswp-slide-animation-duration) var(--pswp-slide-animation-easing) forwards; } @keyframes pswp-slideIn { @@ -103,6 +191,9 @@ const PHOTOSWIPE_STYLES = ` * Safe to call multiple times - will only inject once. * Called automatically by createGalleryLightbox(), so you typically don't need to call this directly. * + * All styles use CSS custom properties that can be overridden by themes. + * See {@link PHOTOSWIPE_CSS_VARS} for available variables. + * * Note: Base PhotoSwipe CSS (photoswipe/style.css) must still be imported in your theme. * This function only injects the enhanced SPG-specific styles. * @@ -114,6 +205,15 @@ const PHOTOSWIPE_STYLES = ` * const lightbox = await createGalleryLightbox(); * lightbox.init(); * ``` + * + * @example Customize in your theme's CSS: + * ```css + * :root { + * --pswp-caption-bg: rgba(0, 20, 40, 0.9); + * --pswp-caption-radius: 8px; + * --pswp-button-color: #3b82f6; + * } + * ``` */ export function injectPhotoSwipeStyles(): void { if (document.querySelector('#spg-photoswipe-styles')) return; From c4f58a63885ff6c6ba7850e0db1c84756afb7482 Mon Sep 17 00:00:00 2001 From: rustoma Date: Fri, 23 Jan 2026 07:41:01 +0100 Subject: [PATCH 37/55] feat: add PhotoSwipe CSS styles and enhance lightbox integration with new import paths --- common/package.json | 3 +- common/src/client/index.ts | 2 +- common/src/client/photoswipe/index.ts | 1 - common/src/client/photoswipe/lightbox.ts | 9 +- .../photoswipe/photoswipe.css} | 91 ------------------- common/tsup.config.ts | 9 ++ .../templates/base/src/pages/index.astro | 1 + .../components/lightbox/PhotoSwipe.astro | 1 + 8 files changed, 19 insertions(+), 98 deletions(-) rename common/src/{client/photoswipe/styles.ts => styles/photoswipe/photoswipe.css} (52%) diff --git a/common/package.json b/common/package.json index cb69872..16e7f6f 100644 --- a/common/package.json +++ b/common/package.json @@ -24,7 +24,8 @@ "./client": { "types": "./dist/client.d.ts", "import": "./dist/client.js" - } + }, + "./styles/photoswipe": "./dist/styles/photoswipe/photoswipe.css" }, "files": [ "dist" diff --git a/common/src/client/index.ts b/common/src/client/index.ts index 0af37e4..c0eada6 100644 --- a/common/src/client/index.ts +++ b/common/src/client/index.ts @@ -7,7 +7,7 @@ export { initHeroImageFallback } from './hero-fallback'; // PhotoSwipe integration export type { GalleryLightboxOptions, VideoPluginOptions } from './photoswipe'; -export { createGalleryLightbox, injectPhotoSwipeStyles, PHOTOSWIPE_CSS_VARS, PhotoSwipeVideoPlugin } from './photoswipe'; +export { createGalleryLightbox, PhotoSwipeVideoPlugin } from './photoswipe'; // CSS utilities export { deriveOpacityColor, normalizeHex, parseColor, setCSSVar } from './css-utils'; diff --git a/common/src/client/photoswipe/index.ts b/common/src/client/photoswipe/index.ts index e60516d..8ae126e 100644 --- a/common/src/client/photoswipe/index.ts +++ b/common/src/client/photoswipe/index.ts @@ -1,5 +1,4 @@ export type { GalleryLightboxOptions } from './lightbox'; export { createGalleryLightbox } from './lightbox'; -export { injectPhotoSwipeStyles, PHOTOSWIPE_CSS_VARS } from './styles'; export type { VideoPluginOptions } from './types'; export { PhotoSwipeVideoPlugin } from './video-plugin'; diff --git a/common/src/client/photoswipe/lightbox.ts b/common/src/client/photoswipe/lightbox.ts index 674b9fc..ee8d3f7 100644 --- a/common/src/client/photoswipe/lightbox.ts +++ b/common/src/client/photoswipe/lightbox.ts @@ -1,4 +1,3 @@ -import { injectPhotoSwipeStyles } from './styles'; import { PhotoSwipeVideoPlugin } from './video-plugin'; import type { VideoPluginOptions } from './types'; @@ -33,10 +32,15 @@ export interface GalleryLightboxOptions { * Create a PhotoSwipe lightbox with sensible defaults and video support. * Returns the lightbox instance for further customization before calling init(). * + * IMPORTANT: You must import the PhotoSwipe CSS files for the lightbox to work properly: + * - `import 'photoswipe/style.css'` - Base PhotoSwipe styles + * - `import '@simple-photo-gallery/common/styles/photoswipe'` - SPG enhancement styles + * * @example * ```typescript * import { createGalleryLightbox } from '@simple-photo-gallery/common/client'; * import 'photoswipe/style.css'; + * import '@simple-photo-gallery/common/styles/photoswipe'; * * // Basic usage * const lightbox = await createGalleryLightbox(); @@ -54,9 +58,6 @@ export interface GalleryLightboxOptions { * ``` */ export async function createGalleryLightbox(options: GalleryLightboxOptions = {}): Promise { - // Inject enhanced styles - safe to call multiple times - injectPhotoSwipeStyles(); - const photoswipeModule = await import('photoswipe'); const PhotoSwipe = photoswipeModule.default; const lightboxModule = await import('photoswipe/lightbox'); diff --git a/common/src/client/photoswipe/styles.ts b/common/src/styles/photoswipe/photoswipe.css similarity index 52% rename from common/src/client/photoswipe/styles.ts rename to common/src/styles/photoswipe/photoswipe.css index 3379ce2..a0092e8 100644 --- a/common/src/client/photoswipe/styles.ts +++ b/common/src/styles/photoswipe/photoswipe.css @@ -1,54 +1,3 @@ -/** - * Available CSS custom properties for PhotoSwipe customization. - * Themes can override these variables in their own stylesheets. - * - * @example - * ```css - * :root { - * --pswp-caption-bg: rgba(0, 20, 40, 0.9); - * --pswp-caption-radius: 8px; - * --pswp-button-color: #3b82f6; - * } - * ``` - */ -export const PHOTOSWIPE_CSS_VARS = { - // Background - bgColor: '--pswp-bg-color', - - // Buttons - buttonColor: '--pswp-button-color', - buttonOpacity: '--pswp-button-opacity', - buttonOpacityHover: '--pswp-button-opacity-hover', - - // Counter - counterColor: '--pswp-counter-color', - counterFontSize: '--pswp-counter-font-size', - - // Caption container - captionBg: '--pswp-caption-bg', - captionBlur: '--pswp-caption-blur', - captionColor: '--pswp-caption-color', - captionPadding: '--pswp-caption-padding', - captionPaddingMobile: '--pswp-caption-padding-mobile', - captionRadius: '--pswp-caption-radius', - captionMargin: '--pswp-caption-margin', - captionMarginMobile: '--pswp-caption-margin-mobile', - captionShadow: '--pswp-caption-shadow', - captionMaxWidth: '--pswp-caption-max-width', - - // Caption typography - captionTitleSize: '--pswp-caption-title-size', - captionTitleWeight: '--pswp-caption-title-weight', - captionTextSize: '--pswp-caption-text-size', - captionTextSizeMobile: '--pswp-caption-text-size-mobile', - captionDescriptionSize: '--pswp-caption-description-size', - - // Animation - slideAnimationDuration: '--pswp-slide-animation-duration', - slideAnimationEasing: '--pswp-slide-animation-easing', -} as const; - -const PHOTOSWIPE_STYLES = ` /* PhotoSwipe CSS Custom Properties - Override these in your theme */ :root { /* Background */ @@ -183,43 +132,3 @@ const PHOTOSWIPE_STYLES = ` from { opacity: 0; } to { opacity: 1; } } -`; - -/** - * Inject PhotoSwipe enhanced styles into the document. - * Includes custom styles for captions, animations, and button hover effects. - * Safe to call multiple times - will only inject once. - * Called automatically by createGalleryLightbox(), so you typically don't need to call this directly. - * - * All styles use CSS custom properties that can be overridden by themes. - * See {@link PHOTOSWIPE_CSS_VARS} for available variables. - * - * Note: Base PhotoSwipe CSS (photoswipe/style.css) must still be imported in your theme. - * This function only injects the enhanced SPG-specific styles. - * - * @example - * ```typescript - * import { createGalleryLightbox } from '@simple-photo-gallery/common/client'; - * import 'photoswipe/style.css'; // Required base styles - * - * const lightbox = await createGalleryLightbox(); - * lightbox.init(); - * ``` - * - * @example Customize in your theme's CSS: - * ```css - * :root { - * --pswp-caption-bg: rgba(0, 20, 40, 0.9); - * --pswp-caption-radius: 8px; - * --pswp-button-color: #3b82f6; - * } - * ``` - */ -export function injectPhotoSwipeStyles(): void { - if (document.querySelector('#spg-photoswipe-styles')) return; - - const style = document.createElement('style'); - style.id = 'spg-photoswipe-styles'; - style.textContent = PHOTOSWIPE_STYLES; - document.head.append(style); -} diff --git a/common/tsup.config.ts b/common/tsup.config.ts index adac965..50336d2 100644 --- a/common/tsup.config.ts +++ b/common/tsup.config.ts @@ -42,5 +42,14 @@ export default defineConfig([ outDir: 'dist', treeshake: true, external: ['photoswipe', 'photoswipe/lightbox', 'blurhash'], + async onSuccess() { + const fs = await import('node:fs/promises'); + + const srcStyles = 'src/styles'; + const distStyles = 'dist/styles'; + + await fs.mkdir(distStyles, { recursive: true }); + await fs.cp(srcStyles, distStyles, { recursive: true }); + }, }, ]); diff --git a/gallery/src/modules/create-theme/templates/base/src/pages/index.astro b/gallery/src/modules/create-theme/templates/base/src/pages/index.astro index 2659c68..85e2f82 100644 --- a/gallery/src/modules/create-theme/templates/base/src/pages/index.astro +++ b/gallery/src/modules/create-theme/templates/base/src/pages/index.astro @@ -51,6 +51,7 @@ const gallery = await resolveGalleryData(raw, { galleryJsonPath }); +``` + +**Implementation:** [common/src/client/](../common/src/client/) + +Client-side features: + +1. **Blurhash Decoding** + - Finds canvas elements with `data-blurhash` attribute + - Decodes blurhash strings to pixel data + - Renders low-quality image placeholders + +2. **PhotoSwipe Lightbox** + - Configures PhotoSwipe with sensible defaults + - Adds video support via custom plugin + - Enables full-screen image viewing + +3. **Hero Image Fallback** + - Transitions from blurhash to actual image + - Smooth fade effect when image loads + - Improves perceived performance + +4. **CSS Utilities** + - Dynamic CSS custom property manipulation + - Color parsing and transformation + - Theme customization support + +--- + +## Theme System Design + +### Theme Package Discovery + +**Local Paths:** +- Theme string starts with `.` or `/`: filesystem path +- Path resolved relative to current working directory +- Must contain valid `package.json` file +- Useful for development and private themes + +**npm Packages:** +- Standard Node.js module resolution +- Searches `node_modules/` directories +- Works with scoped packages (`@organization/theme-name`) +- Supports private npm registries +- Ideal for sharing themes publicly or across projects + +**Example:** +```bash +# Local theme +spg build --theme ./themes/my-theme + +# npm package (installed) +npm install @myorg/custom-theme +spg build --theme @myorg/custom-theme + +# Default theme (no --theme flag) +spg build # Uses @simple-photo-gallery/theme-modern +``` + +### Build Process Integration + +Themes integrate via Astro's static site generation: + +1. **Theme Configuration** ([themes/modern/astro.config.ts](../themes/modern/astro.config.ts)) + ```typescript + const galleryJsonPath = process.env.GALLERY_JSON_PATH; + const outputDir = process.env.GALLERY_OUTPUT_DIR; + + export default defineConfig({ + output: 'static', // Must be static + outDir: `${outputDir}/_build`, // CLI expects _build subdirectory + // ... other config + }); + ``` + +2. **Data Loading** (in theme pages) + ```typescript + import { loadGalleryData, resolveGalleryData } from '@simple-photo-gallery/common/theme'; + + const galleryJsonPath = import.meta.env.GALLERY_JSON_PATH || './gallery.json'; + const raw = loadGalleryData(galleryJsonPath, { validate: true }); + const gallery = await resolveGalleryData(raw, { galleryJsonPath }); + ``` + +3. **Component Rendering** + - Components receive resolved data types + - Use pre-computed paths directly + - No runtime path calculation needed + +4. **Static Output** + - Astro generates `index.html` and assets + - CLI moves output to gallery directory + - Result is fully static, hostable anywhere + +**Key constraint:** Themes MUST use `output: 'static'` and generate `index.html`. The CLI expects this structure and will fail if the build doesn't produce static output. + +### Environment Variable Passing + +#### `GALLERY_JSON_PATH` + +Absolute path to the source `gallery.json` file. + +**Set by:** CLI before invoking Astro build +**Used by:** Theme to load gallery data +**Available as:** `process.env.GALLERY_JSON_PATH` (Node) and `import.meta.env.GALLERY_JSON_PATH` (Vite) + +**Note:** Must be passed to Vite via `define` config for `import.meta.env` access: +```typescript +export default defineConfig({ + vite: { + define: { + 'process.env.GALLERY_JSON_PATH': JSON.stringify(sourceGalleryPath), + }, + }, +}); +``` + +#### `GALLERY_OUTPUT_DIR` + +Directory where the final gallery should be output. + +**Set by:** CLI before invoking Astro build +**Used by:** Theme to set Astro's `outDir` +**Default:** Same directory as `gallery.json` + +**Usage:** +```typescript +const outputDir = process.env.GALLERY_OUTPUT_DIR || galleryJsonPath.replace('gallery.json', ''); + +export default defineConfig({ + outDir: `${outputDir}/_build`, // CLI expects _build subdirectory +}); +``` + +### Why Path Resolution Happens in Common + +**Design Decision:** Themes receive fully-resolved data rather than computing paths themselves. + +**Benefits:** + +1. **Consistency** + - All themes compute paths identically + - No risk of path bugs in individual themes + - Easier to reason about path structure + +2. **Simplicity** + - Themes focus on layout and styling + - No need to understand path computation logic + - Reduces cognitive load for theme developers + +3. **Performance** + - Paths computed once at build time + - No per-component computation + - No runtime overhead + +4. **Flexibility** + - Path logic can evolve in common package + - Themes automatically benefit from improvements + - Bug fixes apply to all themes immediately + +5. **Testability** + - Resolver logic is unit-testable in isolation + - Easier to verify correctness + - Can test edge cases comprehensively + +**Trade-off:** Themes lose some flexibility in custom path logic, but gain reliability and development speed. This is an intentional choice prioritizing consistency over flexibility. + +--- + +## Multi-Theme Support + +### Shared Utilities + +All themes import from `@simple-photo-gallery/common`: + +**Gallery Module** (`.`): +- Raw `GalleryData` types +- Zod validation schemas +- Type definitions for all data structures + +**Theme Module** (`./theme`): +- `loadGalleryData()` - File loading and validation +- `resolveGalleryData()` - Data transformation +- Path utility functions +- Markdown rendering +- Astro integrations + +**Client Module** (`./client`): +- PhotoSwipe lightbox integration +- Blurhash decoding utilities +- Hero image fallback behavior +- CSS manipulation helpers + +**Styles** (`./styles/photoswipe`): +- PhotoSwipe CSS bundle +- Customizable via CSS custom properties + +**This ensures:** +- Consistent behavior across all themes +- Shared bug fixes benefit everyone +- Common package can add features without breaking themes +- Theme developers can focus on presentation + +### Theme Independence + +Themes are independent npm packages with: + +**Own Dependencies:** +- Each theme chooses its Astro version +- Can use different UI libraries +- Can include additional integrations + +**Complete Style Control:** +- Themes own all CSS +- No inherited styles from common +- Full creative freedom + +**Custom Components:** +- Themes can structure components however they want +- No required component hierarchy +- Only constraint: must read `gallery.json` and generate `index.html` + +**Independent Development:** +- Themes can be developed separately +- Can have different maintainers +- Can follow different versioning strategies + +**Example:** A theme could use React components via Astro's framework integrations, while another uses plain Astro components. Both work with the same gallery data. + +### Scaffolding System + +#### Overview + +`spg create-theme ` creates new themes from a base template. + +**Command:** `spg create-theme my-theme [--path ./custom/path]` + +**Implementation:** [gallery/src/modules/create-theme/](../gallery/src/modules/create-theme/) + +#### Template Source + +**Primary Location:** [gallery/src/modules/create-theme/templates/base/](../gallery/src/modules/create-theme/templates/base/) +- Bundled with the CLI package +- Works out-of-the-box after `npm install -g simple-photo-gallery` +- Used in production + +**Fallback Location:** `themes/base/` in workspace root +- Only available during local development +- Allows testing template changes without rebuilding CLI +- Not included in published package + +#### Scaffolding Process + +1. **Validation** + - Theme name must be alphanumeric with optional hyphens + - Validates theme name format: `/^[a-z0-9-]+$/` + +2. **Monorepo Detection** + - Searches for workspace root (looks for `package.json` with `workspaces` field) + - If found: prefer `/themes/` as output location + - Otherwise: use current directory or custom `--path` + +3. **Directory Creation** + - Determine output path + - Verify target directory doesn't exist + - Create parent directories if needed + +4. **Template Copy** + - Copy all files from base template + - **Exclude:** + - `node_modules/` + - `.astro/`, `dist/`, `_build/` + - `.git/`, `.DS_Store` + - `README.md`, `README_BASE.md` (handled separately) + - Log files + +5. **Customization** + - **Update `package.json`:** + - Replace package name with `@simple-photo-gallery/theme-` + - Keep version and dependencies unchanged + + - **Generate `README.md`:** + - Read `README_BASE.md` template + - Replace `{{THEME_NAME}}` placeholders + - Write to `README.md` in new theme + +6. **Completion** + - Print success message with next steps + - Suggest running `yarn install` in theme directory + +#### Base Template Structure + +``` +base/ +├── src/ +│ ├── pages/ +│ │ └── index.astro - Main gallery page +│ ├── features/ +│ │ └── themes/ +│ │ └── base-theme/ - Reusable base theme components +│ │ ├── pages/ - Actual page implementations +│ │ ├── components/ - Gallery components +│ │ ├── layouts/ - HTML structure +│ │ └── scripts/ - Client-side code +│ └── styles/ - Global styles +├── public/ - Static assets +├── astro.config.ts - Astro configuration +├── package.json - Dependencies and scripts +├── tsconfig.json - TypeScript configuration +└── README_BASE.md - Template for generated README +``` + +**Key Pattern:** The template uses a "wrapper + base-theme" structure: +- `src/pages/index.astro` - Simple wrapper that imports BaseTheme +- `src/features/themes/base-theme/` - Actual implementation +- This pattern allows easy customization by modifying the wrapper or extending the base theme + +--- + +## Adding New Features + +### When to Add to Common Package + +Add features to [common/](../common/) when: + +**Cross-Theme Functionality:** +- Feature is needed by multiple themes +- Feature involves shared business logic +- Feature should behave consistently everywhere + +**Examples:** +- New gallery data field → Add to `common/src/gallery/types.ts` and schemas +- Video thumbnail support → Add to `common/src/theme/paths.ts` +- New image transformation → Add to `common/src/theme/resolver.ts` +- Lazy loading utility → Add to `common/src/client/` + +**Data Transformation:** +- Any computation that should happen once at build time +- Path resolution logic +- URL construction +- Responsive image srcset generation + +**Validation:** +- New fields in `gallery.json` structure +- Schema validation logic +- Type definitions + +**Client Utilities:** +- Browser-side helpers that multiple themes might use +- PhotoSwipe extensions +- Animation utilities +- Performance optimizations + +### When to Add to Individual Themes + +Add features to specific theme packages when: + +**Visual/Stylistic:** +- Layout changes +- CSS styling +- Typography choices +- Color schemes + +**Theme-Specific Behavior:** +- Custom navigation patterns +- Unique interaction patterns +- Specialized component variants + +**Examples:** +- Grid layout variations → Theme CSS +- Custom lightbox animations → Theme JavaScript +- Unique hero section design → Theme components +- Brand-specific styling → Theme CSS variables + +### Maintaining Backward Compatibility + +#### Common Package + +**Rules:** +- Never remove exported functions (deprecate instead) +- Add new fields as optional in TypeScript types +- Keep Zod schemas backward-compatible +- Document breaking changes in CHANGELOG +- Consider migration path before major version + +**Example - Adding Optional Field:** +```typescript +// ✅ Good - Optional field +interface GalleryData { + // ... existing fields + newFeature?: string; // Optional +} + +// ❌ Bad - Required field (breaking) +interface GalleryData { + // ... existing fields + newFeature: string; // Required - breaks existing galleries +} +``` + +**Example - Deprecating Function:** +```typescript +// ✅ Good - Deprecate but keep +/** + * @deprecated Use getPhotoPath() instead + */ +export function getImagePath(filename: string): string { + return getPhotoPath(filename); +} +``` + +#### Themes + +**Best Practices:** +- Test against multiple `common` package versions +- Use optional chaining for new fields: `gallery.newFeature?.value` +- Provide sensible fallbacks for missing data +- Document minimum required `common` version in `package.json` + +**Example:** +```typescript +// ✅ Good - Handles missing field gracefully +const feature = gallery.newFeature ?? 'default-value'; + +// ❌ Bad - Assumes field exists +const feature = gallery.newFeature.value; // Runtime error if undefined +``` + +### Testing Across Themes + +When changing the common package: + +1. **Build Common Package** + ```bash + yarn workspace @simple-photo-gallery/common build + ``` + +2. **Test Modern Theme** + ```bash + yarn workspace @simple-photo-gallery/theme-modern build + ``` + Verify no TypeScript errors or build failures + +3. **Create Test Theme** + ```bash + spg create-theme test-theme + cd themes/test-theme + yarn install + ``` + +4. **Test with Real Gallery** + ```bash + # Create test gallery + spg init -p /path/to/photos -g /tmp/test-gallery + + # Build with test theme + spg build --theme ./themes/test-theme -g /tmp/test-gallery + ``` + +5. **Verify Output** + - Open `/tmp/test-gallery/index.html` in browser + - Check console for JavaScript errors + - Verify all features work as expected + - Test responsive behavior + - Verify lightbox functionality + +6. **Cross-Browser Testing** + - Test in Chrome, Firefox, Safari + - Test on mobile devices + - Verify PWA functionality (if applicable) + +--- + +## Key Implementation Files + +| Component | Location | +|-----------|----------| +| Build orchestration | [gallery/src/modules/build/](../gallery/src/modules/build/) | +| Gallery initialization | [gallery/src/modules/init/](../gallery/src/modules/init/) | +| Data loader | [common/src/theme/loader.ts](../common/src/theme/loader.ts) | +| Data resolver | [common/src/theme/resolver.ts](../common/src/theme/resolver.ts) | +| Path utilities | [common/src/theme/paths.ts](../common/src/theme/paths.ts) | +| Markdown rendering | [common/src/theme/markdown.ts](../common/src/theme/markdown.ts) | +| Client utilities | [common/src/client/](../common/src/client/) | +| Blurhash utilities | [common/src/client/blurhash.ts](../common/src/client/blurhash.ts) | +| PhotoSwipe integration | [common/src/client/photoswipe/](../common/src/client/photoswipe/) | +| Gallery types | [common/src/gallery/types.ts](../common/src/gallery/types.ts) | +| Gallery schemas | [common/src/gallery/schemas.ts](../common/src/gallery/schemas.ts) | +| Base template | [gallery/src/modules/create-theme/templates/base/](../gallery/src/modules/create-theme/templates/base/) | +| Modern theme | [themes/modern/](../themes/modern/) | +| Theme base components | [themes/modern/src/features/themes/base-theme/](../themes/modern/src/features/themes/base-theme/) | +| Theme scaffolder | [gallery/src/modules/create-theme/](../gallery/src/modules/create-theme/) | + +--- + +## Design Principles + +### 1. Separation of Concerns + +**CLI** handles: +- Gallery data generation from photos +- Thumbnail creation +- Theme resolution and build orchestration +- File system operations + +**Common** handles: +- Data validation and schemas +- Data transformation and resolution +- Path computation +- Client-side utilities + +**Themes** handle: +- Layout and presentation +- Component structure +- Styling and visual design +- User experience + +This separation allows each package to evolve independently while maintaining clear interfaces between them. + +### 2. Static-First + +Everything is computed at **build time**, not runtime: +- All paths resolved during build +- Markdown parsed to HTML during build +- Responsive srcsets generated during build +- No runtime data transformation + +**Benefits:** +- Fast page loads (no client-side processing) +- Works without JavaScript +- Hostable anywhere (just static files) +- Excellent SEO (all content in HTML) + +### 3. Type Safety + +TypeScript throughout the entire stack: +- Common package exports comprehensive types +- Themes get full IntelliSense support +- Catch errors at development time +- Self-documenting code + +**Example:** +```typescript +import type { ResolvedGalleryData } from '@simple-photo-gallery/common/theme'; + +// TypeScript knows the exact structure +const gallery: ResolvedGalleryData = await resolveGalleryData(raw); +gallery.sections[0].images // ✅ TypeScript validates this +``` + +### 4. Developer Experience + +**Simple scaffolding:** +```bash +spg create-theme my-theme # One command to start +``` + +**Clear utilities:** +```typescript +// Intuitive API +const gallery = await resolveGalleryData(raw); +const lightbox = createGalleryLightbox(); +``` + +**Good defaults:** +- PhotoSwipe configured out of the box +- Sensible path resolution +- Validation enabled by default + +**Comprehensive documentation:** +- API reference in common README +- Architecture guide (this document) +- Theme development guide +- Command documentation + +### 5. Flexibility + +**Multiple theme sources:** +- npm packages (public or private) +- Local filesystem paths +- Default theme built-in + +**Extensibility:** +- Themes can add custom features +- Common package is extensible +- Plugin system via Astro integrations + +**No lock-in:** +- Themes are just npm packages +- Can fork and customize +- Can create completely custom themes + +--- + +## See Also + +- [Common Package API](../common/README.md) - Complete API reference +- [Custom Themes Guide](./themes.md) - Theme development guide +- [Commands Reference](./commands/README.md) - CLI documentation +- [Modern Theme Source](../themes/modern/) - Reference implementation +- [Gallery Configuration](./configuration.md) - gallery.json manual editing diff --git a/docs/themes.md b/docs/themes.md index 3a94222..df73ba8 100644 --- a/docs/themes.md +++ b/docs/themes.md @@ -154,7 +154,69 @@ This is your main theme entry point. It must: - Parse and use the `GalleryData` structure - Generate valid HTML output -Example: +**Recommended approach** - Use the resolver utilities from `@simple-photo-gallery/common/theme`: + +```astro +--- +import { loadGalleryData, resolveGalleryData } from '@simple-photo-gallery/common/theme'; +import type { ResolvedGalleryData } from '@simple-photo-gallery/common/theme'; + +// Read gallery.json from the path provided by the build process +const galleryJsonPath = import.meta.env.GALLERY_JSON_PATH || './gallery.json'; + +// Load and resolve gallery data +const raw = loadGalleryData(galleryJsonPath, { validate: true }); +const gallery: ResolvedGalleryData = await resolveGalleryData(raw, { galleryJsonPath }); + +// Extract resolved gallery properties +const { hero, sections, subGalleries, metadata } = gallery; +--- + + + + {hero.title} + + {metadata.analyticsScript && ( + + )} + + + +

{hero.title}

+
+ + + + + + + + {hero.title} + + + + {sections.map((section) => ( +
+

{section.title}

+
+ ))} + + +``` + +**Alternative - Manual approach** (not recommended for new themes): ```astro --- @@ -166,41 +228,24 @@ const galleryJsonPath = process.env.GALLERY_JSON_PATH || './gallery.json'; const galleryData = JSON.parse(fs.readFileSync(galleryJsonPath, 'utf8')); const gallery = galleryData as GalleryData; -// Extract gallery properties -const { - title, - description, - metadata, - sections, - subGalleries, - mediaBaseUrl, - thumbsBaseUrl, - url, - analyticsScript, - headerImage, - headerImageBlurHash, - ctaBanner, -} = gallery; +// Extract gallery properties - note: paths and markdown NOT pre-computed +const { title, description, sections } = gallery; --- {title} - {analyticsScript && ( - - )} -

{title}

{description}

- + {sections.map((section) => (
{section.images.map((image) => ( - {image.caption + {image.alt ))}
))} @@ -208,9 +253,19 @@ const { ``` +> **Note:** The resolver approach is recommended because it provides pre-computed paths, responsive srcsets, and parsed markdown. The modern theme uses this pattern. See the [Common Package API](../common/README.md) for complete documentation. + ### Gallery Data Structure -Your theme receives a `GalleryData` object with the following structure: +> **Important:** There are two data structures to understand: +> - **`GalleryData`** - Raw structure from `gallery.json` (manual approach) +> - **`ResolvedGalleryData`** - Transformed structure with pre-computed paths (recommended approach) +> +> **Recommendation:** Use `resolveGalleryData()` from `@simple-photo-gallery/common/theme` to get resolved data. This is what the modern theme uses. + +#### Raw GalleryData (Manual Approach) + +Your theme receives a `GalleryData` object from `gallery.json` with the following structure: ```typescript interface GalleryData { @@ -268,6 +323,89 @@ interface GalleryData { } ``` +### Using Common Package Utilities + +The `@simple-photo-gallery/common` package provides utilities that make theme development easier and more consistent. + +#### Data Loading and Resolution + +**`loadGalleryData()`** - Load gallery.json with optional validation: + +```typescript +import { loadGalleryData } from '@simple-photo-gallery/common/theme'; + +const gallery = loadGalleryData('./gallery.json', { validate: true }); +``` + +**`resolveGalleryData()`** - Transform raw data into resolved structure: + +```typescript +import { resolveGalleryData } from '@simple-photo-gallery/common/theme'; + +const resolved = await resolveGalleryData(gallery, { galleryJsonPath: './gallery.json' }); + +// Access pre-computed data +resolved.hero.src // Computed hero image path +resolved.hero.srcsets // Responsive image srcsets +resolved.sections[0].parsedDescription // HTML from markdown +resolved.sections[0].images[0].imagePath // Computed image path +``` + +**Benefits of using the resolver:** +- All image paths pre-computed (no manual path logic) +- Responsive srcsets built automatically +- Markdown descriptions parsed to HTML +- Type-safe with `ResolvedGalleryData` type + +#### Client-Side Utilities + +The `@simple-photo-gallery/common/client` module provides browser-side utilities: + +**PhotoSwipe Lightbox:** +```typescript +import { createGalleryLightbox } from '@simple-photo-gallery/common/client'; + +const lightbox = createGalleryLightbox({ + gallery: '#gallery', + children: 'a' +}); +lightbox.init(); +``` + +**Blurhash Decoding:** +```typescript +import { decodeAllBlurhashes } from '@simple-photo-gallery/common/client'; + +// Decodes all canvas elements with data-blurhash attribute +decodeAllBlurhashes(); +``` + +**Hero Image Fallback:** +```typescript +import { initHeroImageFallback } from '@simple-photo-gallery/common/client'; + +// Smooth transition from blurhash to actual image +initHeroImageFallback(); +``` + +**CSS Utilities:** +```typescript +import { setCSSVar, deriveOpacityColor } from '@simple-photo-gallery/common/client'; + +// Set CSS custom properties dynamically +setCSSVar('--primary-color', '#007bff'); + +// Create semi-transparent colors +const bgColor = deriveOpacityColor('#007bff', 0.1); +setCSSVar('--bg-color', bgColor); +``` + +#### Complete API Reference + +For a comprehensive list of all utilities and types, see the [Common Package API documentation](../common/README.md). + +--- + ### Environment Variables The build process sets these environment variables that your theme can access: @@ -314,12 +452,14 @@ yarn dev ### Best Practices -1. **Use TypeScript**: Import types from `@simple-photo-gallery/common` for type safety -2. **Handle optional fields**: Many fields in `GalleryData` are optional - always check before using -3. **Respect base URLs**: Use `mediaBaseUrl` and `thumbsBaseUrl` when provided for external hosting -4. **Optimize assets**: Use Astro's asset optimization features -5. **Test locally**: Use `astro dev` to preview your theme during development -6. **Follow Astro conventions**: Use Astro components, layouts, and best practices +1. **Use the resolver**: Use `resolveGalleryData()` from `@simple-photo-gallery/common/theme` for path computation and data transformation (recommended) +2. **Use TypeScript**: Import types from `@simple-photo-gallery/common` for type safety +3. **Leverage client utilities**: Import from `@simple-photo-gallery/common/client` for browser-side functionality like PhotoSwipe and blurhash +4. **Handle optional fields**: Many fields in `GalleryData` are optional - always check before using +5. **Use resolved types**: Work with `ResolvedGalleryData`, `ResolvedHero`, `ResolvedSection`, etc. for pre-computed data +6. **Optimize assets**: Use Astro's asset optimization features +7. **Test locally**: Use `astro dev` to preview your theme during development +8. **Follow Astro conventions**: Use Astro components, layouts, and best practices ### Example Theme Packages From d240f1fe835ec6804c42f7aa74e16b66c4fb9c2a Mon Sep 17 00:00:00 2001 From: rustoma Date: Fri, 23 Jan 2026 20:53:30 +0100 Subject: [PATCH 41/55] feat: implement theme configuration support for thumbnails, enhancing gallery customization options --- common/README.md | 182 ++++++++++++------ common/src/gallery/schemas.ts | 7 +- common/src/styles/photoswipe/photoswipe.css | 8 +- common/src/theme/config.ts | 44 +++++ common/src/theme/index.ts | 6 +- common/src/theme/loader.ts | 47 +++++ common/src/theme/resolver.ts | 23 ++- common/src/theme/types.ts | 6 + docs/commands/init.md | 15 +- docs/configuration.md | 73 ++++++- docs/themes.md | 70 ++++++- .../base/src/components/GalleryItem.astro | 57 ++++++ .../base/src/layouts/MainLayout.astro | 6 +- .../templates/base/src/pages/index.astro | 57 ++---- .../templates/base/themeConfig.json | 6 + gallery/src/modules/init/index.ts | 68 ++++++- gallery/src/modules/init/types/index.ts | 7 + gallery/src/modules/thumbnails/index.ts | 60 +++++- gallery/src/utils/gallery.ts | 6 + gallery/src/utils/image.ts | 22 ++- gallery/src/utils/video.ts | 33 +++- gallery/tests/migration.test.ts | 2 +- themes/modern/astro.config.ts | 1 - .../gallery-section/GallerySection.astro | 12 +- .../gallery-section/GallerySectionItem.astro | 29 +-- .../base-theme/components/hero/Hero.astro | 1 - .../sub-galleries/SubGalleries.astro | 4 +- .../base-theme/layouts/MainLayout.astro | 7 +- .../themes/base-theme/pages/index.astro | 15 +- themes/modern/themeConfig.json | 6 + 30 files changed, 701 insertions(+), 179 deletions(-) create mode 100644 common/src/theme/config.ts create mode 100644 gallery/src/modules/create-theme/templates/base/src/components/GalleryItem.astro create mode 100644 gallery/src/modules/create-theme/templates/base/themeConfig.json create mode 100644 themes/modern/themeConfig.json diff --git a/common/README.md b/common/README.md index 0525349..bfa3302 100644 --- a/common/README.md +++ b/common/README.md @@ -28,13 +28,11 @@ Theme utilities for loading and transforming gallery data. Loads and optionally validates gallery.json. ```typescript -function loadGalleryData( - galleryJsonPath?: string, - options?: LoadGalleryDataOptions -): GalleryData +function loadGalleryData(galleryJsonPath?: string, options?: LoadGalleryDataOptions): GalleryData; ``` **Parameters:** + - `galleryJsonPath` (optional): Path to gallery.json file. Defaults to `'./gallery.json'` - `options` (optional): - `validate?: boolean` - Enable Zod schema validation (default: `false`) @@ -44,6 +42,7 @@ function loadGalleryData( **Throws:** Error if file cannot be read, parsed, or fails validation **Example:** + ```typescript import { loadGalleryData } from '@simple-photo-gallery/common/theme'; @@ -56,39 +55,99 @@ const gallery = loadGalleryData('./gallery.json', { validate: true }); --- +#### `loadThemeConfig(themePath?)` + +Loads theme configuration from themeConfig.json file. + +```typescript +function loadThemeConfig(themePath?: string): ThumbnailConfig | undefined; +``` + +**Parameters:** + +- `themePath` (optional): Path to the theme directory containing themeConfig.json + +**Returns:** `ThumbnailConfig` object with thumbnail settings, or `undefined` if not found + +**Searches in order:** + +1. Current working directory (`process.cwd()/themeConfig.json`) +2. Provided `themePath` parameter (`themePath/themeConfig.json`) + +**Example:** + +```typescript +import path from 'node:path'; +import { loadThemeConfig } from '@simple-photo-gallery/common/theme'; + +// Load from theme directory +const themePath = path.resolve(import.meta.dirname, '../..'); +const themeConfig = loadThemeConfig(themePath); + +// Use in data resolution +const gallery = await resolveGalleryData(raw, { + galleryJsonPath: './gallery.json', + themeConfig, +}); +``` + +**Theme Configuration Structure:** + +```json +{ + "thumbnails": { + "size": 300, + "edge": "height" + } +} +``` + +--- + #### `resolveGalleryData(data, options?)` Transforms raw data into fully-resolved structure with pre-computed paths and parsed markdown. ```typescript -async function resolveGalleryData( - data: GalleryData, - options?: ResolveGalleryDataOptions -): Promise +async function resolveGalleryData(data: GalleryData, options?: ResolveGalleryDataOptions): Promise; ``` **Parameters:** + - `data`: Raw `GalleryData` object (from `loadGalleryData()`) - `options` (optional): - `galleryJsonPath?: string` - Path to gallery.json, enables relative path resolution for sub-galleries + - `themeConfig?: ThumbnailConfig` - Theme-level thumbnail configuration (from `loadThemeConfig()`) **Returns:** `ResolvedGalleryData` with: + - Pre-computed image and thumbnail paths - Built responsive image srcsets for hero - Parsed markdown descriptions as HTML - Computed properties for sub-galleries +- Resolved thumbnail configuration (merged from gallery.json, theme config, and defaults) **Example:** + ```typescript -import { loadGalleryData, resolveGalleryData } from '@simple-photo-gallery/common/theme'; +import path from 'node:path'; +import { loadGalleryData, loadThemeConfig, resolveGalleryData } from '@simple-photo-gallery/common/theme'; const raw = loadGalleryData('./gallery.json', { validate: true }); -const gallery = await resolveGalleryData(raw, { galleryJsonPath: './gallery.json' }); + +// Load theme config (optional, for theme-level thumbnail defaults) +const themePath = path.resolve(import.meta.dirname, '../..'); +const themeConfig = loadThemeConfig(themePath); + +const gallery = await resolveGalleryData(raw, { + galleryJsonPath: './gallery.json', + themeConfig, +}); // Access resolved data -console.log(gallery.hero.src); // Pre-computed hero path -console.log(gallery.hero.srcsets); // Responsive srcsets -console.log(gallery.sections[0].parsedDescription); // HTML from markdown +console.log(gallery.hero.src); // Pre-computed hero path +console.log(gallery.hero.srcsets); // Responsive srcsets +console.log(gallery.sections[0].parsedDescription); // HTML from markdown ``` --- @@ -100,11 +159,7 @@ console.log(gallery.sections[0].parsedDescription); // HTML from markdown Resolves media file path with optional base URL. ```typescript -function getPhotoPath( - filename: string, - baseUrl?: string, - url?: string -): string +function getPhotoPath(filename: string, baseUrl?: string, url?: string): string; ``` --- @@ -114,11 +169,7 @@ function getPhotoPath( Resolves thumbnail path with optional base URL. ```typescript -function getThumbnailPath( - path: string, - baseUrl?: string, - thumbBaseUrl?: string -): string +function getThumbnailPath(path: string, baseUrl?: string, thumbBaseUrl?: string): string; ``` --- @@ -135,8 +186,8 @@ function buildHeroSrcset( basename: string, orientation: 'landscape' | 'portrait', format: 'avif' | 'jpg', - useDefaultPaths: boolean -): string + useDefaultPaths: boolean, +): string; ``` --- @@ -146,7 +197,7 @@ function buildHeroSrcset( Computes relative path between two locations. ```typescript -function getRelativePath(to: string, from: string): string +function getRelativePath(to: string, from: string): string; ``` --- @@ -156,7 +207,7 @@ function getRelativePath(to: string, from: string): string Computes thumbnail path for sub-gallery header images. ```typescript -function getSubgalleryThumbnailPath(headerImage: string): string +function getSubgalleryThumbnailPath(headerImage: string): string; ``` --- @@ -168,10 +219,11 @@ function getSubgalleryThumbnailPath(headerImage: string): string Parses markdown to HTML with limited formatting (no headings, images, HTML, or tables). ```typescript -async function renderMarkdown(markdown: string): Promise +async function renderMarkdown(markdown: string): Promise; ``` **Example:** + ```typescript import { renderMarkdown } from '@simple-photo-gallery/common/theme'; @@ -186,10 +238,11 @@ const html = await renderMarkdown('**Bold** and *italic* text'); Astro integration that removes empty content collection files after build. ```typescript -function preventEmptyContentFiles(): AstroIntegration +function preventEmptyContentFiles(): AstroIntegration; ``` **Example:** + ```typescript // In astro.config.ts import { preventEmptyContentFiles } from '@simple-photo-gallery/common/theme'; @@ -232,7 +285,8 @@ interface ResolvedGalleryData { hero: ResolvedHero; sections: ResolvedSection[]; subGalleries?: ResolvedSubGallery[]; - // ... other metadata + thumbnails?: Required; // Resolved thumbnail configuration + // ... other metadata (url, metadata, analyticsScript, etc.) } ``` @@ -321,9 +375,27 @@ Options for `resolveGalleryData()`. ```typescript interface ResolveGalleryDataOptions { galleryJsonPath?: string; + themeConfig?: ThumbnailConfig; } ``` +#### `ThumbnailConfig` + +Thumbnail configuration settings. + +```typescript +interface ThumbnailConfig { + size?: number; // Thumbnail size in pixels (default: 300) + edge?: 'auto' | 'width' | 'height'; // How size is applied (default: 'auto') +} +``` + +**Edge Options:** + +- `'auto'`: Applied to longer edge (default behavior) +- `'width'`: Applied to width (good for masonry layouts) +- `'height'`: Applied to height (good for row-based layouts) + --- ## Client Module (`@simple-photo-gallery/common/client`) @@ -337,10 +409,11 @@ Browser-side utilities for client-side functionality. Decodes all blurhash canvases on the page (elements with `data-blurhash` attribute). ```typescript -function decodeAllBlurhashes(): void +function decodeAllBlurhashes(): void; ``` **Example:** + ```typescript import { decodeAllBlurhashes } from '@simple-photo-gallery/common/client'; @@ -349,6 +422,7 @@ decodeAllBlurhashes(); ``` **HTML:** + ```html ``` @@ -360,10 +434,7 @@ decodeAllBlurhashes(); Decodes a single blurhash to a canvas element. ```typescript -function decodeBlurhashToCanvas( - canvas: HTMLCanvasElement, - blurhash: string -): void +function decodeBlurhashToCanvas(canvas: HTMLCanvasElement, blurhash: string): void; ``` --- @@ -375,12 +446,11 @@ function decodeBlurhashToCanvas( Creates a configured PhotoSwipe lightbox instance with video support. ```typescript -function createGalleryLightbox( - options?: GalleryLightboxOptions -): PhotoSwipeLightbox +function createGalleryLightbox(options?: GalleryLightboxOptions): PhotoSwipeLightbox; ``` **Parameters:** + - `options` (optional): - `gallery?: string` - Gallery element selector (default: `'#gallery'`) - `children?: string` - Child elements selector (default: `'a'`) @@ -390,12 +460,13 @@ function createGalleryLightbox( **Returns:** Configured PhotoSwipe lightbox instance (call `.init()` to activate) **Example:** + ```typescript import { createGalleryLightbox } from '@simple-photo-gallery/common/client'; const lightbox = createGalleryLightbox({ gallery: '#my-gallery', - children: 'a.gallery-item' + children: 'a.gallery-item', }); lightbox.init(); @@ -424,23 +495,23 @@ class PhotoSwipeVideoPlugin { Initializes hero image fallback behavior (transitions from blur hash to actual image). ```typescript -function initHeroImageFallback( - options?: HeroImageFallbackOptions -): void +function initHeroImageFallback(options?: HeroImageFallbackOptions): void; ``` **Parameters:** + - `options` (optional): - `heroSelector?: string` - Hero element selector (default: `'.hero'`) - `imageSelector?: string` - Hero image selector (default: `'.hero__image'`) **Example:** + ```typescript import { initHeroImageFallback } from '@simple-photo-gallery/common/client'; initHeroImageFallback({ heroSelector: '.my-hero', - imageSelector: '.my-hero img' + imageSelector: '.my-hero img', }); ``` @@ -453,14 +524,11 @@ initHeroImageFallback({ Sets a CSS custom property value. ```typescript -function setCSSVar( - name: string, - value: string, - element?: HTMLElement -): void +function setCSSVar(name: string, value: string, element?: HTMLElement): void; ``` **Example:** + ```typescript import { setCSSVar } from '@simple-photo-gallery/common/client'; @@ -479,7 +547,7 @@ setCSSVar('--hero-bg', '#000', hero); Parses a color string to RGB array. ```typescript -function parseColor(color: string): [number, number, number] | null +function parseColor(color: string): [number, number, number] | null; ``` **Supports:** Hex colors (`#fff`, `#ffffff`) and RGB strings (`rgb(255, 0, 0)`) @@ -491,13 +559,14 @@ function parseColor(color: string): [number, number, number] | null Normalizes a hex color to 6-character format. ```typescript -function normalizeHex(hex: string): string +function normalizeHex(hex: string): string; ``` **Example:** + ```typescript -normalizeHex('#fff'); // Returns: '#ffffff' -normalizeHex('#ffffff'); // Returns: '#ffffff' +normalizeHex('#fff'); // Returns: '#ffffff' +normalizeHex('#ffffff'); // Returns: '#ffffff' ``` --- @@ -507,13 +576,11 @@ normalizeHex('#ffffff'); // Returns: '#ffffff' Derives an RGBA color from a base color and opacity. ```typescript -function deriveOpacityColor( - baseColor: string, - opacity: number -): string +function deriveOpacityColor(baseColor: string, opacity: number): string; ``` **Example:** + ```typescript import { deriveOpacityColor } from '@simple-photo-gallery/common/client'; @@ -661,6 +728,7 @@ All types have corresponding Zod validation schemas: - `HeaderImageVariantsSchema` - Validates responsive image variants **Example:** + ```typescript import { GalleryDataSchema } from '@simple-photo-gallery/common'; @@ -741,7 +809,7 @@ initHeroImageFallback(); // Setup PhotoSwipe lightbox const lightbox = createGalleryLightbox({ gallery: '#gallery', - children: 'a' + children: 'a', }); lightbox.init(); ``` diff --git a/common/src/gallery/schemas.ts b/common/src/gallery/schemas.ts index 246e054..f2103f1 100644 --- a/common/src/gallery/schemas.ts +++ b/common/src/gallery/schemas.ts @@ -120,7 +120,12 @@ export const GalleryDataSchema = z.object({ headerImage: z.string(), headerImageBlurHash: z.string().optional(), headerImageVariants: HeaderImageVariantsSchema.optional(), - thumbnailSize: z.number().optional(), + thumbnails: z + .object({ + size: z.number().optional(), + edge: z.enum(['auto', 'width', 'height']).optional(), + }) + .optional(), metadata: GalleryMetadataSchema, mediaBaseUrl: z.string().optional(), thumbsBaseUrl: z.string().optional(), diff --git a/common/src/styles/photoswipe/photoswipe.css b/common/src/styles/photoswipe/photoswipe.css index a0092e8..09862f8 100644 --- a/common/src/styles/photoswipe/photoswipe.css +++ b/common/src/styles/photoswipe/photoswipe.css @@ -129,6 +129,10 @@ } @keyframes pswp-slideIn { - from { opacity: 0; } - to { opacity: 1; } + from { + opacity: 0; + } + to { + opacity: 1; + } } diff --git a/common/src/theme/config.ts b/common/src/theme/config.ts new file mode 100644 index 0000000..a89c898 --- /dev/null +++ b/common/src/theme/config.ts @@ -0,0 +1,44 @@ +import { z } from 'zod'; + +/** Zod schema for thumbnail configuration */ +export const ThumbnailConfigSchema = z.object({ + size: z.number().optional(), + edge: z.enum(['auto', 'width', 'height']).optional(), +}); + +/** Zod schema for theme configuration file (themeConfig.json) */ +export const ThemeConfigSchema = z.object({ + thumbnails: ThumbnailConfigSchema.optional(), +}); + +/** TypeScript type for thumbnail configuration */ +export type ThumbnailConfig = z.infer; + +/** TypeScript type for theme configuration */ +export type ThemeConfig = z.infer; + +/** Default thumbnail configuration values */ +export const DEFAULT_THUMBNAIL_CONFIG: Required = { + size: 300, + edge: 'auto', +}; + +/** + * Merges thumbnail configurations with hierarchy: + * 1. CLI flags / gallery.json (highest precedence) + * 2. themeConfig.json (theme defaults) + * 3. Built-in defaults (lowest) + * + * @param galleryConfig - Config from gallery.json or CLI flags + * @param themeConfig - Config from themeConfig.json (optional) + * @returns Merged thumbnail configuration with all values resolved + */ +export function mergeThumbnailConfig( + galleryConfig?: ThumbnailConfig, + themeConfig?: ThumbnailConfig, +): Required { + return { + size: galleryConfig?.size ?? themeConfig?.size ?? DEFAULT_THUMBNAIL_CONFIG.size, + edge: galleryConfig?.edge ?? themeConfig?.edge ?? DEFAULT_THUMBNAIL_CONFIG.edge, + }; +} diff --git a/common/src/theme/index.ts b/common/src/theme/index.ts index 4562d61..a6bd2d7 100644 --- a/common/src/theme/index.ts +++ b/common/src/theme/index.ts @@ -1,6 +1,10 @@ // Types export type { ResolvedGalleryData, ResolvedHero, ResolvedImage, ResolvedSection, ResolvedSubGallery } from './types'; +// Theme config +export type { ThemeConfig, ThumbnailConfig } from './config'; +export { DEFAULT_THUMBNAIL_CONFIG, mergeThumbnailConfig, ThemeConfigSchema, ThumbnailConfigSchema } from './config'; + // Constants export { LANDSCAPE_SIZES, PORTRAIT_SIZES } from './constants'; @@ -12,7 +16,7 @@ export { buildHeroSrcset, getPhotoPath, getRelativePath, getSubgalleryThumbnailP // Gallery loading export type { LoadGalleryDataOptions } from './loader'; -export { loadGalleryData } from './loader'; +export { loadGalleryData, loadThemeConfig } from './loader'; // Data resolution export type { ResolveGalleryDataOptions } from './resolver'; diff --git a/common/src/theme/loader.ts b/common/src/theme/loader.ts index 7e15b93..d1a5f28 100644 --- a/common/src/theme/loader.ts +++ b/common/src/theme/loader.ts @@ -1,4 +1,8 @@ import fs from 'node:fs'; +import path from 'node:path'; +import process from 'node:process'; + +import { ThemeConfigSchema, type ThumbnailConfig } from './config'; import { GalleryDataSchema, type GalleryData } from '../gallery'; @@ -11,6 +15,49 @@ export interface LoadGalleryDataOptions { validate?: boolean; } +/** + * Load theme configuration from themeConfig.json file. + * + * Searches for themeConfig.json in the following locations: + * 1. Current working directory (process.cwd()) + * 2. Provided themePath parameter + * + * @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(); + * ``` + */ +export function loadThemeConfig(themePath?: string): ThumbnailConfig | undefined { + const themeConfigPaths: string[] = [path.resolve(process.cwd(), 'themeConfig.json')]; + + if (themePath) { + themeConfigPaths.push(path.resolve(themePath, 'themeConfig.json')); + } + + for (const configPath of themeConfigPaths) { + if (fs.existsSync(configPath)) { + try { + const configData = JSON.parse(fs.readFileSync(configPath, 'utf8')); + const parsed = ThemeConfigSchema.safeParse(configData); + if (parsed.success) { + return parsed.data.thumbnails; + } + } catch { + // Ignore parse errors and continue searching + } + } + } + + return undefined; +} + /** * Load gallery data from a JSON file. * diff --git a/common/src/theme/resolver.ts b/common/src/theme/resolver.ts index 815b781..117b133 100644 --- a/common/src/theme/resolver.ts +++ b/common/src/theme/resolver.ts @@ -1,5 +1,6 @@ import path from 'node:path'; +import { mergeThumbnailConfig, type ThumbnailConfig } from './config'; import { LANDSCAPE_SIZES, PORTRAIT_SIZES } from './constants'; import { renderMarkdown } from './markdown'; import { buildHeroSrcset, getPhotoPath, getRelativePath, getSubgalleryThumbnailPath, getThumbnailPath } from './paths'; @@ -7,6 +8,16 @@ import { buildHeroSrcset, getPhotoPath, getRelativePath, getSubgalleryThumbnailP import type { GalleryData, GallerySection, MediaFile, SubGallery } from '../gallery'; import type { ResolvedGalleryData, ResolvedHero, ResolvedImage, ResolvedSection, ResolvedSubGallery } from './types'; +/** + * Extracts thumbnail config from gallery data. + */ +function extractThumbnailConfigFromGallery(gallery: GalleryData): ThumbnailConfig { + return { + size: gallery.thumbnails?.size, + edge: gallery.thumbnails?.edge, + }; +} + /** * Resolve a single image with all paths computed. */ @@ -146,6 +157,11 @@ export interface ResolveGalleryDataOptions { * 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; } /** @@ -161,7 +177,7 @@ export async function resolveGalleryData( options?: ResolveGalleryDataOptions, ): Promise { const { mediaBaseUrl, thumbsBaseUrl, subGalleries } = gallery; - const { galleryJsonPath } = options ?? {}; + const { galleryJsonPath, themeConfig } = options ?? {}; const hero = await resolveHero(gallery); const sections = await Promise.all( @@ -175,6 +191,10 @@ export async function resolveGalleryData( } : undefined; + // Merge thumbnail config: gallery.json > themeConfig > defaults + const galleryThumbnailConfig = extractThumbnailConfigFromGallery(gallery); + const thumbnails = mergeThumbnailConfig(galleryThumbnailConfig, themeConfig); + return { title: gallery.title, url: gallery.url, @@ -186,5 +206,6 @@ export async function resolveGalleryData( subGalleries: resolvedSubGalleries, mediaBaseUrl, thumbsBaseUrl, + thumbnails, }; } diff --git a/common/src/theme/types.ts b/common/src/theme/types.ts index e827fc9..04b0951 100644 --- a/common/src/theme/types.ts +++ b/common/src/theme/types.ts @@ -1,4 +1,5 @@ import type { GalleryMetadata, HeaderImageVariants } from '../gallery'; +import type { ThumbnailConfig } from './config'; /** Resolved hero data with all paths computed and markdown parsed */ export interface ResolvedHero { @@ -68,4 +69,9 @@ export interface ResolvedGalleryData { // Pass through base URLs for components that need them 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; } diff --git a/docs/commands/init.md b/docs/commands/init.md index eb703e4..2638285 100644 --- a/docs/commands/init.md +++ b/docs/commands/init.md @@ -8,11 +8,22 @@ spg init [options] ## How it works -This command initializes a new gallery by scanning a folder (and optionally its subfolders) for images and videos. The command will prompt you to enter the gallery title, description, header image, and URL where it will be hosted. All of these can later be edited in the `gallery.json` file. +This command initializes a new gallery by scanning a folder (and optionally its subfolders) for images and videos. The command will prompt you to enter: + +- Gallery title +- Gallery description +- Header image (selected from your photos) +- URL where the gallery will be hosted +- Thumbnail size (in pixels) - optional, press Enter to use theme/default settings +- Thumbnail edge mode (auto/width/height) - optional, press Enter to use theme/default settings + +All of these settings can later be edited in the `gallery.json` file. > **Note:** The URL is important if you want the automatically generated social media images to work correctly, as it needs to be an absolute URL. -After that, the command will create a `gallery` folder and a `gallery.json` file in it. The `gallery.json` file contains all the information about the gallery, including the title, description, header image, URL and all images and videos in the gallery. +> **Tip:** For thumbnail settings, you can press Enter to skip the prompts. This allows the [configuration hierarchy](../configuration.md#thumbnail-configuration) to work: gallery.json → themeConfig.json → built-in defaults (300px, auto edge). + +After that, the command will create a `gallery` folder and a `gallery.json` file in it. The `gallery.json` file contains all the information about the gallery, including the title, description, header image, URL, thumbnail settings (if specified), and all images and videos in the gallery. ## Options diff --git a/docs/configuration.md b/docs/configuration.md index ba90183..1c60188 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -237,9 +237,78 @@ Markdown formatting is available in: - **Images** and **tables** are not supported for security and layout consistency - **HTML tags** are stripped for security -## Thumbnail size +## Thumbnail Configuration -Thumbnails will automatically be generated using sizes that fit the theme (300px height and 600px height for retina displays). If you want, you can change the size using the `thumbnailSize` attribute in the `gallery.json` file. +Thumbnail generation and display can be configured through a hierarchical configuration system: + +1. **Gallery-level configuration** (highest priority) - Set in `gallery.json` +2. **Theme-level configuration** - Set in theme's `themeConfig.json` file +3. **Built-in defaults** (lowest priority) - 300px on auto (longer edge) + +### Configuration Hierarchy + +The thumbnail settings follow this priority order: + +``` +gallery.json > themeConfig.json > built-in defaults +``` + +This means if you specify thumbnail settings in `gallery.json`, those will be used. If not, the theme's `themeConfig.json` will be checked. If neither is set, the built-in defaults (300px, auto edge) will be used. + +### Gallery-level Configuration + +You can override thumbnail settings per gallery by adding a `thumbnails` object to your `gallery.json`: + +```json +{ + "title": "My Gallery", + "thumbnails": { + "size": 400, + "edge": "height" + } +} +``` + +**Options:** + +- `size` (number): The thumbnail size in pixels. Default: `300` +- `edge` (string): How the size is applied. Default: `"auto"` + - `"auto"` - Applied to the longer edge (default behavior) + - `"width"` - Applied to width (good for masonry layouts) + - `"height"` - Applied to height (good for row-based layouts like modern theme) + +### Theme-level Configuration + +Themes can provide their own default thumbnail settings by including a `themeConfig.json` file in the theme root directory: + +```json +{ + "thumbnails": { + "size": 300, + "edge": "height" + } +} +``` + +This allows theme authors to set optimal defaults for their specific layout while still allowing users to override these settings per gallery. + +**For theme developers:** Place `themeConfig.json` in your theme's root directory (same level as `package.json`). The configuration will be automatically loaded when the theme is used. + +### Display Behavior + +When thumbnails are configured, they also control the display size in themes: + +- **Modern theme**: `thumbnails.size` becomes the row height (e.g., `size: 200` sets `--row-height: 200px`) +- **Default behavior** (no thumbnails config): Uses responsive breakpoints (96px on mobile, scaling up to 160px on desktop) + +### Interactive Configuration + +When running `gallery init`, you'll be prompted to configure thumbnail settings. You can: +- Enter a custom size (in pixels) +- Choose how the size is applied (auto/width/height) +- Press Enter to skip and use theme/default settings + +Only explicitly set values will be saved to `gallery.json`, keeping the file clean and allowing the configuration hierarchy to work properly. ## Header image variants diff --git a/docs/themes.md b/docs/themes.md index df73ba8..0444824 100644 --- a/docs/themes.md +++ b/docs/themes.md @@ -75,6 +75,7 @@ Your theme package should have the following structure: ``` your-theme-package/ ├── package.json +├── themeConfig.json (optional, but recommended) ├── astro.config.ts ├── tsconfig.json └── src/ @@ -146,7 +147,56 @@ export default defineConfig({ }); ``` -#### 3. `src/pages/index.astro` +#### 3. `themeConfig.json` (Optional, but recommended) + +Theme authors can provide default configuration for their theme by including a `themeConfig.json` file in the theme root directory (same level as `package.json`). + +This allows you to set optimal defaults for your theme's layout while still allowing users to override these settings per gallery in their `gallery.json` file. + +**Example themeConfig.json:** + +```json +{ + "thumbnails": { + "size": 300, + "edge": "height" + } +} +``` + +**Configuration Options:** + +- `thumbnails.size` (number): Default thumbnail size in pixels (default: 300) +- `thumbnails.edge` (string): How the size is applied + - `"auto"`: Applied to longer edge (default) + - `"width"`: Applied to width (good for masonry layouts) + - `"height"`: Applied to height (good for row-based layouts) + +**Configuration Hierarchy:** + +The thumbnail settings follow this priority order: + +1. **Gallery-level** (highest priority): Settings in user's `gallery.json` +2. **Theme-level**: Settings in theme's `themeConfig.json` +3. **Built-in defaults** (lowest priority): 300px on auto (longer edge) + +This means users can override your theme defaults per gallery, while your theme provides sensible defaults that work well with its layout. + +**Loading Theme Config:** + +Use the `loadThemeConfig()` utility from `@simple-photo-gallery/common/theme`: + +```typescript +import path from 'node:path'; +import { loadThemeConfig } from '@simple-photo-gallery/common/theme'; + +const themePath = path.resolve(import.meta.dirname, '../..'); +const themeConfig = loadThemeConfig(themePath); +``` + +See the example in section 3 below for complete integration. + +#### 4. `src/pages/index.astro` This is your main theme entry point. It must: @@ -158,18 +208,28 @@ This is your main theme entry point. It must: ```astro --- -import { loadGalleryData, resolveGalleryData } from '@simple-photo-gallery/common/theme'; +import path from 'node:path'; +import { loadGalleryData, loadThemeConfig, resolveGalleryData } from '@simple-photo-gallery/common/theme'; import type { ResolvedGalleryData } from '@simple-photo-gallery/common/theme'; // Read gallery.json from the path provided by the build process const galleryJsonPath = import.meta.env.GALLERY_JSON_PATH || './gallery.json'; -// Load and resolve gallery data +// Load gallery data const raw = loadGalleryData(galleryJsonPath, { validate: true }); -const gallery: ResolvedGalleryData = await resolveGalleryData(raw, { galleryJsonPath }); + +// Load theme config (optional, for theme-level defaults) +const themePath = path.resolve(import.meta.dirname, '../..'); +const themeConfig = loadThemeConfig(themePath); + +// Resolve gallery data with theme config +const gallery: ResolvedGalleryData = await resolveGalleryData(raw, { + galleryJsonPath, + themeConfig +}); // Extract resolved gallery properties -const { hero, sections, subGalleries, metadata } = gallery; +const { hero, sections, subGalleries, metadata, thumbnails } = gallery; --- diff --git a/gallery/src/modules/create-theme/templates/base/src/components/GalleryItem.astro b/gallery/src/modules/create-theme/templates/base/src/components/GalleryItem.astro new file mode 100644 index 0000000..971fe0e --- /dev/null +++ b/gallery/src/modules/create-theme/templates/base/src/components/GalleryItem.astro @@ -0,0 +1,57 @@ +--- +import { renderMarkdown } from '@simple-photo-gallery/common/theme'; +import type { ResolvedImage } from '@simple-photo-gallery/common/theme'; + +interface Props { + image: ResolvedImage; +} + +const { image } = Astro.props; + +const parsedCaption = image.alt ? await renderMarkdown(image.alt) : ''; +const captionHtml = parsedCaption ? `
${parsedCaption}
` : ''; +--- + + + {image.alt + {image.alt && {image.alt}} + + + diff --git a/gallery/src/modules/create-theme/templates/base/src/layouts/MainLayout.astro b/gallery/src/modules/create-theme/templates/base/src/layouts/MainLayout.astro index 4ccfb34..1c29558 100644 --- a/gallery/src/modules/create-theme/templates/base/src/layouts/MainLayout.astro +++ b/gallery/src/modules/create-theme/templates/base/src/layouts/MainLayout.astro @@ -4,6 +4,7 @@ import path from 'node:path'; import MainHead from '@/layouts/MainHead.astro'; import type { GalleryMetadata } from '@simple-photo-gallery/common'; +import type { ThumbnailConfig } from '@simple-photo-gallery/common/theme'; interface Props { title: string; @@ -13,9 +14,10 @@ interface Props { metadata?: GalleryMetadata; analyticsScript?: string; headerImage?: string; + thumbnails?: Required; } -const { title, description, metadata, url, thumbsBaseUrl, analyticsScript, headerImage } = Astro.props; +const { title, description, metadata, url, thumbsBaseUrl, analyticsScript, headerImage, thumbnails } = Astro.props; // Extract basename from headerImage filename const headerImageBasename = headerImage ? path.basename(headerImage, path.extname(headerImage)) : undefined; @@ -31,7 +33,7 @@ const headerImageBasename = headerImage ? path.basename(headerImage, path.extnam thumbsBaseUrl={thumbsBaseUrl} headerImageBasename={headerImageBasename} /> - + {analyticsScript && } diff --git a/gallery/src/modules/create-theme/templates/base/src/pages/index.astro b/gallery/src/modules/create-theme/templates/base/src/pages/index.astro index 1d487e2..95327b7 100644 --- a/gallery/src/modules/create-theme/templates/base/src/pages/index.astro +++ b/gallery/src/modules/create-theme/templates/base/src/pages/index.astro @@ -1,13 +1,21 @@ --- -import { loadGalleryData, resolveGalleryData } from '@simple-photo-gallery/common/theme'; +import path from 'node:path'; +import { loadGalleryData, loadThemeConfig, resolveGalleryData } from '@simple-photo-gallery/common/theme'; + +import GalleryItem from '@/components/GalleryItem.astro'; import Hero from '@/components/Hero.astro'; import MainLayout from '@/layouts/MainLayout.astro'; // Load and resolve gallery data - all paths are pre-computed const galleryJsonPath = import.meta.env.GALLERY_JSON_PATH || './gallery.json'; const raw = loadGalleryData(galleryJsonPath, { validate: true }); -const gallery = await resolveGalleryData(raw, { galleryJsonPath }); + +// Load theme config from theme root or cwd +const themePath = path.resolve(import.meta.dirname, '../..'); +const themeConfig = loadThemeConfig(themePath); + +const gallery = await resolveGalleryData(raw, { galleryJsonPath, themeConfig }); --- + headerImage={gallery.hero.headerImage} + thumbnails={gallery.thumbnails}>
@@ -30,16 +39,7 @@ const gallery = await resolveGalleryData(raw, { galleryJsonPath });
{section.images.map((image) => ( - - {image.alt - {image.alt && {image.alt}} - + ))}
@@ -102,36 +102,5 @@ const gallery = await resolveGalleryData(raw, { galleryJsonPath }); margin-top: 2rem; } - .gallery-item { - position: relative; - display: block; - overflow: hidden; - border-radius: 8px; - cursor: pointer; - aspect-ratio: 1; - } - - .gallery-item img { - width: 100%; - height: 100%; - object-fit: cover; - transition: transform 0.3s ease; - } - - .gallery-item:hover img { - transform: scale(1.05); - } - - .caption { - position: absolute; - bottom: 0; - left: 0; - right: 0; - background: linear-gradient(to top, rgba(0, 0, 0, 0.7), transparent); - color: white; - padding: 1rem; - font-size: 0.9rem; - } - /* TODO: Customize styles to match your design */ diff --git a/gallery/src/modules/create-theme/templates/base/themeConfig.json b/gallery/src/modules/create-theme/templates/base/themeConfig.json new file mode 100644 index 0000000..87c6d3c --- /dev/null +++ b/gallery/src/modules/create-theme/templates/base/themeConfig.json @@ -0,0 +1,6 @@ +{ + "thumbnails": { + "size": 300, + "edge": "auto" + } +} diff --git a/gallery/src/modules/init/index.ts b/gallery/src/modules/init/index.ts index d6e3b85..b7131d1 100644 --- a/gallery/src/modules/init/index.ts +++ b/gallery/src/modules/init/index.ts @@ -84,8 +84,43 @@ async function getGallerySettingsFromUser( default: defaultImage, placeholder: defaultImage, }); + const thumbnailSize = await ui.prompt('Enter thumbnail size in pixels (or press Enter to skip and use theme/default)', { + type: 'text', + default: '', + placeholder: 'theme default or 300', + }); + + const thumbnailEdgeOption = (await ui.prompt( + 'How should thumbnail size be applied?\n - auto: Applied to the longer edge (recommended for mixed orientations)\n - width: Applied to width (for masonry layouts)\n - height: Applied to height (for row-based layouts)\n (Press Enter to skip and use theme/default)', + { + type: 'select', + options: ['Skip (use theme/default)', 'auto (longer edge)', 'width (masonry)', 'height (rows)'], + initial: 'Skip (use theme/default)', + }, + )) as string; + + // Extract edge from selected option - only set if not skipped + let thumbnailEdge: 'auto' | 'width' | 'height' | undefined = undefined; + if (!thumbnailEdgeOption.startsWith('Skip')) { + if (thumbnailEdgeOption.startsWith('auto')) { + thumbnailEdge = 'auto'; + } else if (thumbnailEdgeOption.startsWith('width')) { + thumbnailEdge = 'width'; + } else { + thumbnailEdge = 'height'; + } + } - return { title, description, url, headerImage }; + return { + title, + description, + url, + headerImage, + thumbnails: { + size: thumbnailSize, + edge: thumbnailEdge, + }, + }; } /** @@ -138,13 +173,34 @@ async function createGalleryJson( }; if (!useDefaultSettings) { + const userSettings = await getGallerySettingsFromUser( + path.basename(path.join(galleryDir, '..')), + path.basename(mediaFiles[0]?.filename || ''), + ui, + ); + + // Extract thumbnail settings and only include if actually set by user + const { thumbnails, ...otherSettings } = userSettings; + const parsedSize = thumbnails.size.length > 0 ? Number.parseInt(thumbnails.size, 10) : undefined; + + // Build thumbnails config only with values explicitly set by user + const thumbnailsConfig: { size?: number; edge?: 'auto' | 'width' | 'height' } = {}; + + // Only include size if user entered a value (not empty) + if (parsedSize !== undefined && !Number.isNaN(parsedSize)) { + thumbnailsConfig.size = parsedSize; + } + + // Only include edge if user selected a value (not skipped) + if (thumbnails.edge !== undefined) { + thumbnailsConfig.edge = thumbnails.edge; + } + galleryData = { ...galleryData, - ...(await getGallerySettingsFromUser( - path.basename(path.join(galleryDir, '..')), - path.basename(mediaFiles[0]?.filename || ''), - ui, - )), + ...otherSettings, + // Only include thumbnails object if user set at least one value + ...(Object.keys(thumbnailsConfig).length > 0 && { thumbnails: thumbnailsConfig }), }; } diff --git a/gallery/src/modules/init/types/index.ts b/gallery/src/modules/init/types/index.ts index bd1bfb3..1e8a8f5 100644 --- a/gallery/src/modules/init/types/index.ts +++ b/gallery/src/modules/init/types/index.ts @@ -57,4 +57,11 @@ export interface GallerySettingsFromUser { url: string; /** Path to the header image */ headerImage: string; + /** Thumbnail configuration */ + thumbnails: { + /** Size of generated thumbnails in pixels (empty string if not set) */ + size: string; + /** How thumbnail size should be applied: 'auto', 'width', or 'height' (undefined if not set) */ + edge: 'auto' | 'width' | 'height' | undefined; + }; } diff --git a/gallery/src/modules/thumbnails/index.ts b/gallery/src/modules/thumbnails/index.ts index 93dad92..937e017 100644 --- a/gallery/src/modules/thumbnails/index.ts +++ b/gallery/src/modules/thumbnails/index.ts @@ -1,21 +1,34 @@ import fs from 'node:fs'; import path from 'node:path'; +import { mergeThumbnailConfig } from '@simple-photo-gallery/common/theme'; import { LogLevels, type ConsolaInstance } from 'consola'; import { getFileMtime } from './utils'; -import { DEFAULT_THUMBNAIL_SIZE } from '../../config'; import { findGalleries, handleFileProcessingError } from '../../utils'; import { generateBlurHash } from '../../utils/blurhash'; import { getImageDescription } from '../../utils/descriptions'; import { parseGalleryJson } from '../../utils/gallery'; -import { createImageThumbnails, loadImageWithMetadata } from '../../utils/image'; +import { createImageThumbnails, loadImageWithMetadata, type ThumbnailSizeDimension } from '../../utils/image'; import { getVideoDimensions, createVideoThumbnails } from '../../utils/video'; import type { ThumbnailOptions } from './types'; import type { CommandResultSummary } from '../telemetry/types'; -import type { MediaFile } from '@simple-photo-gallery/common'; +import type { GalleryData, MediaFile } from '@simple-photo-gallery/common'; +import type { ThumbnailConfig } from '@simple-photo-gallery/common/theme'; + +/** + * Extracts thumbnail config from gallery data. + * @param galleryData - The gallery data object + * @returns ThumbnailConfig with values from gallery.json + */ +function extractThumbnailConfigFromGallery(galleryData: GalleryData): ThumbnailConfig { + return { + size: galleryData.thumbnails?.size, + edge: galleryData.thumbnails?.edge, + }; +} /** * Processes an image file to create thumbnail and extract metadata @@ -23,6 +36,7 @@ import type { MediaFile } from '@simple-photo-gallery/common'; * @param thumbnailPath - Path where thumbnail should be saved * @param thumbnailPathRetina - Path where retina thumbnail should be saved * @param thumbnailSize - Target size for thumbnail + * @param thumbnailSizeDimension - How to apply size: 'auto', 'width', or 'height' * @param lastMediaTimestamp - Optional timestamp to check if processing can be skipped * @returns Promise resolving to updated MediaFile or undefined if skipped */ @@ -31,6 +45,7 @@ export async function processImage( thumbnailPath: string, thumbnailPathRetina: string, thumbnailSize: number, + thumbnailSizeDimension: ThumbnailSizeDimension = 'auto', lastMediaTimestamp?: Date, ): Promise { // Get the last media timestamp @@ -64,6 +79,7 @@ export async function processImage( thumbnailPath, thumbnailPathRetina, thumbnailSize, + thumbnailSizeDimension, ); // Generate BlurHash from the thumbnail @@ -93,6 +109,7 @@ export async function processImage( * @param thumbnailPath - Path where thumbnail should be saved * @param thumbnailPathRetina - Path where retina thumbnail should be saved * @param thumbnailSize - Target size for thumbnail + * @param thumbnailSizeDimension - How to apply size: 'auto', 'width', or 'height' * @param verbose - Whether to enable verbose output * @param lastMediaTimestamp - Optional timestamp to check if processing can be skipped * @returns Promise resolving to updated MediaFile or undefined if skipped @@ -102,6 +119,7 @@ async function processVideo( thumbnailPath: string, thumbnailPathRetina: string, thumbnailSize: number, + thumbnailSizeDimension: ThumbnailSizeDimension = 'auto', verbose: boolean, lastMediaTimestamp?: Date, ): Promise { @@ -123,6 +141,7 @@ async function processVideo( thumbnailPath, thumbnailPathRetina, thumbnailSize, + thumbnailSizeDimension, verbose, ); @@ -150,9 +169,8 @@ async function processVideo( * Processes a media file to generate thumbnails and update metadata * @param mediaFile - Media file to process * @param mediaBasePath - Base path for the media files - * @param galleryDir - Path to the gallery directory * @param thumbnailsPath - Directory where thumbnails are stored - * @param thumbnailSize - Target size for thumbnails + * @param thumbnailConfig - Thumbnail configuration (dimension and edge) * @param ui - ConsolaInstance for logging * @returns Promise resolving to updated MediaFile */ @@ -160,7 +178,7 @@ async function processMediaFile( mediaFile: MediaFile, mediaBasePath: string, thumbnailsPath: string, - thumbnailSize: number, + thumbnailConfig: Required, ui: ConsolaInstance, ): Promise { try { @@ -179,8 +197,23 @@ async function processMediaFile( ui.debug(` Processing ${mediaFile.type}: ${fileName}`); const updatedMediaFile = await (mediaFile.type === 'image' - ? processImage(filePath, thumbnailPath, thumbnailPathRetina, thumbnailSize, lastMediaTimestamp) - : processVideo(filePath, thumbnailPath, thumbnailPathRetina, thumbnailSize, verbose, lastMediaTimestamp)); + ? processImage( + filePath, + thumbnailPath, + thumbnailPathRetina, + thumbnailConfig.size, + thumbnailConfig.edge, + lastMediaTimestamp, + ) + : processVideo( + filePath, + thumbnailPath, + thumbnailPathRetina, + thumbnailConfig.size, + thumbnailConfig.edge, + verbose, + lastMediaTimestamp, + )); if (!updatedMediaFile) { ui.debug(` Skipping ${fileName} because it has already been processed`); @@ -245,7 +278,14 @@ export async function processGalleryThumbnails(galleryDir: string, ui: ConsolaIn // Read gallery.json const galleryData = parseGalleryJson(galleryJsonPath, ui); - const thumbnailSize = galleryData.thumbnailSize || DEFAULT_THUMBNAIL_SIZE; + // Extract thumbnail config from gallery.json + const galleryThumbnailConfig = extractThumbnailConfigFromGallery(galleryData); + + // Merge with defaults (no theme config when running thumbnails command directly) + // Hierarchy: gallery.json > built-in defaults + const thumbnailConfig = mergeThumbnailConfig(galleryThumbnailConfig); + + ui.debug(`Thumbnail config: size=${thumbnailConfig.size}, edge=${thumbnailConfig.edge}`); // If the mediaBasePath is not set, use the gallery directory const mediaBasePath = galleryData.mediaBasePath ?? path.join(galleryDir); @@ -254,7 +294,7 @@ export async function processGalleryThumbnails(galleryDir: string, ui: ConsolaIn let processedCount = 0; for (const section of galleryData.sections) { for (const [index, mediaFile] of section.images.entries()) { - section.images[index] = await processMediaFile(mediaFile, mediaBasePath, thumbnailsPath, thumbnailSize, ui); + section.images[index] = await processMediaFile(mediaFile, mediaBasePath, thumbnailsPath, thumbnailConfig, ui); } processedCount += section.images.length; diff --git a/gallery/src/utils/gallery.ts b/gallery/src/utils/gallery.ts index bf49507..0254b77 100644 --- a/gallery/src/utils/gallery.ts +++ b/gallery/src/utils/gallery.ts @@ -77,11 +77,17 @@ export function migrateGalleryJson( })), })); + // Migrate thumbnailSize to new thumbnails.size format if present + const thumbnails = + deprecatedGalleryData.thumbnailSize === undefined ? undefined : { size: deprecatedGalleryData.thumbnailSize }; + const galleryData = { ...deprecatedGalleryData, + thumbnailSize: undefined, // Remove old field headerImage: path.basename(deprecatedGalleryData.headerImage), sections, mediaBasePath, + thumbnails, }; // Backup the old gallery.json file diff --git a/gallery/src/utils/image.ts b/gallery/src/utils/image.ts index 158a8ff..57bed32 100644 --- a/gallery/src/utils/image.ts +++ b/gallery/src/utils/image.ts @@ -79,13 +79,17 @@ export async function cropAndResizeImage( .toFile(outputPath); } +/** Type for how thumbnail size should be applied */ +export type ThumbnailSizeDimension = 'auto' | 'width' | 'height'; + /** * Creates regular and retina thumbnails for an image while maintaining aspect ratio * @param image - Sharp image instance * @param metadata - Image metadata containing dimensions * @param outputPath - Path where thumbnail should be saved * @param outputPathRetina - Path where retina thumbnail should be saved - * @param size - Target size of the longer side of the thumbnail + * @param size - Target size for the thumbnail + * @param sizeDimension - How to apply the size: 'auto' (longer edge), 'width', or 'height' * @returns Promise resolving to thumbnail dimensions */ export async function createImageThumbnails( @@ -94,6 +98,7 @@ export async function createImageThumbnails( outputPath: string, outputPathRetina: string, size: number, + sizeDimension: ThumbnailSizeDimension = 'auto', ): Promise { // Get the original dimensions const originalWidth = metadata.width || 0; @@ -109,12 +114,23 @@ export async function createImageThumbnails( let width: number; let height: number; - if (originalWidth > originalHeight) { + if (sizeDimension === 'width') { + // Apply size to width, calculate height from aspect ratio width = size; height = Math.round(size / aspectRatio); - } else { + } else if (sizeDimension === 'height') { + // Apply size to height, calculate width from aspect ratio width = Math.round(size * aspectRatio); height = size; + } else { + // 'auto': Apply size to longer edge (original behavior) + if (originalWidth > originalHeight) { + width = size; + height = Math.round(size / aspectRatio); + } else { + width = Math.round(size * aspectRatio); + height = size; + } } // Resize the image and create the thumbnails diff --git a/gallery/src/utils/video.ts b/gallery/src/utils/video.ts index ae42a02..fd724b0 100644 --- a/gallery/src/utils/video.ts +++ b/gallery/src/utils/video.ts @@ -4,7 +4,7 @@ import { promises as fs } from 'node:fs'; import ffprobe from 'node-ffprobe'; import sharp from 'sharp'; -import { resizeImage } from './image'; +import { resizeImage, type ThumbnailSizeDimension } from './image'; import type { Dimensions } from '../types'; import type { Buffer } from 'node:buffer'; @@ -41,7 +41,8 @@ export async function getVideoDimensions(filePath: string): Promise * @param videoDimensions - Original video dimensions * @param outputPath - Path where thumbnail should be saved * @param outputPathRetina - Path where retina thumbnail should be saved - * @param height - Target height for thumbnail + * @param size - Target size for thumbnail + * @param sizeDimension - How to apply size: 'auto' (longer edge), 'width', or 'height' * @param verbose - Whether to enable verbose ffmpeg output * @returns Promise resolving to thumbnail dimensions */ @@ -50,12 +51,34 @@ export async function createVideoThumbnails( videoDimensions: Dimensions, outputPath: string, outputPathRetina: string, - height: number, + size: number, + sizeDimension: ThumbnailSizeDimension = 'auto', verbose: boolean = false, ): Promise { - // Calculate width maintaining aspect ratio + // Calculate dimensions maintaining aspect ratio based on sizeDimension const aspectRatio = videoDimensions.width / videoDimensions.height; - const width = Math.round(height * aspectRatio); + + let width: number; + let height: number; + + if (sizeDimension === 'width') { + // Apply size to width, calculate height from aspect ratio + width = size; + height = Math.round(size / aspectRatio); + } else if (sizeDimension === 'height') { + // Apply size to height, calculate width from aspect ratio + width = Math.round(size * aspectRatio); + height = size; + } else { + // 'auto': Apply size to longer edge + if (videoDimensions.width > videoDimensions.height) { + width = size; + height = Math.round(size / aspectRatio); + } else { + width = Math.round(size * aspectRatio); + height = size; + } + } // Use ffmpeg to extract first frame as a temporary file, then process with sharp const tempFramePath = `${outputPath}.temp.png`; diff --git a/gallery/tests/migration.test.ts b/gallery/tests/migration.test.ts index 2cd78da..d4681e5 100644 --- a/gallery/tests/migration.test.ts +++ b/gallery/tests/migration.test.ts @@ -618,7 +618,7 @@ describe('Gallery JSON Migration', () => { expect(migratedData.title).toBe('My Gallery Title'); expect(migratedData.description).toBe('My Gallery Description'); expect(migratedData.url).toBe('https://example.com'); - expect(migratedData.thumbnailSize).toBe(300); + expect(migratedData.thumbnails?.size).toBe(300); expect(migratedData.analyticsScript).toBe('analytics.js'); expect(migratedData.metadata.image).toBe('/gallery/images/social.jpg'); expect(migratedData.metadata.ogUrl).toBe('https://example.com/gallery'); diff --git a/themes/modern/astro.config.ts b/themes/modern/astro.config.ts index ab5bbc1..d9e5b35 100644 --- a/themes/modern/astro.config.ts +++ b/themes/modern/astro.config.ts @@ -2,7 +2,6 @@ import { preventEmptyContentFiles } from '@simple-photo-gallery/common/theme'; import { defineConfig } from 'astro/config'; import relativeLinks from 'astro-relative-links'; - // Dynamically import gallery.json from source path or fallback to local const sourceGalleryPath = process.env.GALLERY_JSON_PATH; if (!sourceGalleryPath) throw new Error('GALLERY_JSON_PATH environment variable is not set'); diff --git a/themes/modern/src/features/themes/base-theme/components/gallery-section/GallerySection.astro b/themes/modern/src/features/themes/base-theme/components/gallery-section/GallerySection.astro index be15828..b37d637 100644 --- a/themes/modern/src/features/themes/base-theme/components/gallery-section/GallerySection.astro +++ b/themes/modern/src/features/themes/base-theme/components/gallery-section/GallerySection.astro @@ -58,12 +58,14 @@ const validImages = section.images.filter( margin-bottom: 1rem; } + /* Spacer element to prevent last row items from stretching. + Uses a large flex-grow to absorb remaining space, keeping items at natural size. + min-width ensures the spacer takes up remaining space on incomplete rows. */ .gallery-section__gallery::after { - --w: 2; - --h: 1; - --ratio: calc(var(--w) / var(--h)); content: ''; - flex-basis: calc(var(--ratio) * var(--row-height)); - flex-grow: 1000000; + flex-grow: 999999999; + flex-shrink: 0; + flex-basis: var(--row-height); + min-width: var(--row-height); } diff --git a/themes/modern/src/features/themes/base-theme/components/gallery-section/GallerySectionItem.astro b/themes/modern/src/features/themes/base-theme/components/gallery-section/GallerySectionItem.astro index f94219d..8054d66 100644 --- a/themes/modern/src/features/themes/base-theme/components/gallery-section/GallerySectionItem.astro +++ b/themes/modern/src/features/themes/base-theme/components/gallery-section/GallerySectionItem.astro @@ -41,15 +41,16 @@ const captionHtml = parsedCaption ? `
diff --git a/themes/modern/src/features/themes/base-theme/components/hero/Hero.astro b/themes/modern/src/features/themes/base-theme/components/hero/Hero.astro index 747920d..4c18548 100644 --- a/themes/modern/src/features/themes/base-theme/components/hero/Hero.astro +++ b/themes/modern/src/features/themes/base-theme/components/hero/Hero.astro @@ -3,7 +3,6 @@ import HeroScrollToGalleryBtn from '@/features/themes/base-theme/components/hero import type { ResolvedHero } from '@simple-photo-gallery/common/theme'; - interface Props { hero: ResolvedHero; } diff --git a/themes/modern/src/features/themes/base-theme/components/sub-galleries/SubGalleries.astro b/themes/modern/src/features/themes/base-theme/components/sub-galleries/SubGalleries.astro index bd98044..86eb522 100644 --- a/themes/modern/src/features/themes/base-theme/components/sub-galleries/SubGalleries.astro +++ b/themes/modern/src/features/themes/base-theme/components/sub-galleries/SubGalleries.astro @@ -83,7 +83,7 @@ const { title, subGalleries } = Astro.props; } .sub-galleries__item:hover { - transform: scale(1.02) translateY(-5px); + transform: scale(1.002) translateY(-5px); box-shadow: 0 20px 25px -5px rgba(0, 0, 0, 0.1); } @@ -101,7 +101,7 @@ const { title, subGalleries } = Astro.props; } .sub-galleries__item:hover .sub-galleries__item-image img { - transform: scale(1.05); + transform: scale(1.005); } .sub-galleries__item-content { diff --git a/themes/modern/src/features/themes/base-theme/layouts/MainLayout.astro b/themes/modern/src/features/themes/base-theme/layouts/MainLayout.astro index 7a9a10b..6baa00e 100644 --- a/themes/modern/src/features/themes/base-theme/layouts/MainLayout.astro +++ b/themes/modern/src/features/themes/base-theme/layouts/MainLayout.astro @@ -4,6 +4,7 @@ import path from 'node:path'; import MainHead from '@/features/themes/base-theme/layouts/MainHead.astro'; import type { GalleryMetadata, HeaderImageVariants } from '@simple-photo-gallery/common'; +import type { ThumbnailConfig } from '@simple-photo-gallery/common/theme'; interface Props { title: string; @@ -14,9 +15,11 @@ interface Props { analyticsScript?: string; headerImage?: string; headerImageVariants?: HeaderImageVariants; + thumbnails?: Required; } -const { title, description, metadata, url, thumbsBaseUrl, analyticsScript, headerImage, headerImageVariants } = Astro.props; +const { title, description, metadata, url, thumbsBaseUrl, analyticsScript, headerImage, headerImageVariants, thumbnails } = + Astro.props; // Extract basename from headerImage filename const headerImageBasename = headerImage ? path.basename(headerImage, path.extname(headerImage)) : undefined; @@ -33,7 +36,7 @@ const headerImageBasename = headerImage ? path.basename(headerImage, path.extnam headerImageBasename={headerImageBasename} headerImageVariants={headerImageVariants} /> - + {analyticsScript && } diff --git a/themes/modern/src/features/themes/base-theme/pages/index.astro b/themes/modern/src/features/themes/base-theme/pages/index.astro index 2308a34..9061e12 100644 --- a/themes/modern/src/features/themes/base-theme/pages/index.astro +++ b/themes/modern/src/features/themes/base-theme/pages/index.astro @@ -1,5 +1,7 @@ --- -import { loadGalleryData, resolveGalleryData } from '@simple-photo-gallery/common/theme'; +import path from 'node:path'; + +import { loadGalleryData, loadThemeConfig, resolveGalleryData } from '@simple-photo-gallery/common/theme'; import CtaBanner from '@/features/themes/base-theme/components/cta/CtaBanner.astro'; import Footer from '@/features/themes/base-theme/components/footer/Footer.astro'; @@ -12,7 +14,13 @@ import MainLayout from '@/features/themes/base-theme/layouts/MainLayout.astro'; // Load and resolve gallery data - all paths are pre-computed const galleryJsonPath = import.meta.env.GALLERY_JSON_PATH || './gallery.json'; const raw = loadGalleryData(galleryJsonPath, { validate: true }); -const gallery = await resolveGalleryData(raw, { galleryJsonPath }); + +// Load theme config from theme root or cwd +// Try current working directory first, then relative to built theme location +const themePath = path.resolve(import.meta.dirname, '../../../..'); +const themeConfig = loadThemeConfig(themePath); + +const gallery = await resolveGalleryData(raw, { galleryJsonPath, themeConfig }); const showCtaBanner = gallery.ctaBanner === true; --- @@ -37,7 +45,8 @@ const showCtaBanner = gallery.ctaBanner === true; thumbsBaseUrl={gallery.thumbsBaseUrl} analyticsScript={gallery.analyticsScript} headerImage={gallery.hero.headerImage} - headerImageVariants={gallery.hero.headerImageVariants}> + headerImageVariants={gallery.hero.headerImageVariants} + thumbnails={gallery.thumbnails}> { diff --git a/themes/modern/themeConfig.json b/themes/modern/themeConfig.json new file mode 100644 index 0000000..c85a933 --- /dev/null +++ b/themes/modern/themeConfig.json @@ -0,0 +1,6 @@ +{ + "thumbnails": { + "size": 300, + "edge": "height" + } +} From ba1dae23e6d0ade67fb5da3880929c0fd3b88dd1 Mon Sep 17 00:00:00 2001 From: rustoma Date: Sat, 24 Jan 2026 06:35:56 +0100 Subject: [PATCH 42/55] feat: enhance thumbnail configuration with extraction function and validation improvements --- common/src/theme/config.ts | 14 +- common/src/theme/index.ts | 8 +- common/src/theme/loader.ts | 11 +- common/src/theme/resolver.ts | 12 +- gallery/jest.config.cjs | 1 + gallery/src/modules/thumbnails/index.ts | 16 +-- gallery/tests/theme-config.test.ts | 179 ++++++++++++++++++++++++ 7 files changed, 212 insertions(+), 29 deletions(-) create mode 100644 gallery/tests/theme-config.test.ts diff --git a/common/src/theme/config.ts b/common/src/theme/config.ts index a89c898..b0fee99 100644 --- a/common/src/theme/config.ts +++ b/common/src/theme/config.ts @@ -2,7 +2,7 @@ import { z } from 'zod'; /** Zod schema for thumbnail configuration */ export const ThumbnailConfigSchema = z.object({ - size: z.number().optional(), + size: z.number().min(50).max(4000).optional(), edge: z.enum(['auto', 'width', 'height']).optional(), }); @@ -23,6 +23,18 @@ export const DEFAULT_THUMBNAIL_CONFIG: Required = { edge: 'auto', }; +/** + * Extracts thumbnail config from gallery data. + * @param gallery - The gallery data object + * @returns ThumbnailConfig with values from gallery data + */ +export function extractThumbnailConfigFromGallery(gallery: { thumbnails?: ThumbnailConfig }): ThumbnailConfig { + return { + size: gallery.thumbnails?.size, + edge: gallery.thumbnails?.edge, + }; +} + /** * Merges thumbnail configurations with hierarchy: * 1. CLI flags / gallery.json (highest precedence) diff --git a/common/src/theme/index.ts b/common/src/theme/index.ts index a6bd2d7..5473588 100644 --- a/common/src/theme/index.ts +++ b/common/src/theme/index.ts @@ -3,7 +3,13 @@ export type { ResolvedGalleryData, ResolvedHero, ResolvedImage, ResolvedSection, // Theme config export type { ThemeConfig, ThumbnailConfig } from './config'; -export { DEFAULT_THUMBNAIL_CONFIG, mergeThumbnailConfig, ThemeConfigSchema, ThumbnailConfigSchema } from './config'; +export { + DEFAULT_THUMBNAIL_CONFIG, + extractThumbnailConfigFromGallery, + mergeThumbnailConfig, + ThemeConfigSchema, + ThumbnailConfigSchema, +} from './config'; // Constants export { LANDSCAPE_SIZES, PORTRAIT_SIZES } from './constants'; diff --git a/common/src/theme/loader.ts b/common/src/theme/loader.ts index d1a5f28..f46f64d 100644 --- a/common/src/theme/loader.ts +++ b/common/src/theme/loader.ts @@ -49,8 +49,15 @@ export function loadThemeConfig(themePath?: string): ThumbnailConfig | undefined if (parsed.success) { return parsed.data.thumbnails; } - } catch { - // Ignore parse errors and continue searching + // Log validation errors for debugging + if (process.env.DEBUG || process.env.VERBOSE) { + console.warn(`Failed to validate themeConfig at ${configPath}:`, parsed.error.message); + } + } catch (error) { + // Log parse errors for debugging + if (process.env.DEBUG || process.env.VERBOSE) { + console.warn(`Failed to parse themeConfig at ${configPath}:`, error); + } } } } diff --git a/common/src/theme/resolver.ts b/common/src/theme/resolver.ts index 117b133..a3a04ec 100644 --- a/common/src/theme/resolver.ts +++ b/common/src/theme/resolver.ts @@ -1,6 +1,6 @@ import path from 'node:path'; -import { mergeThumbnailConfig, type ThumbnailConfig } from './config'; +import { extractThumbnailConfigFromGallery, mergeThumbnailConfig, type ThumbnailConfig } from './config'; import { LANDSCAPE_SIZES, PORTRAIT_SIZES } from './constants'; import { renderMarkdown } from './markdown'; import { buildHeroSrcset, getPhotoPath, getRelativePath, getSubgalleryThumbnailPath, getThumbnailPath } from './paths'; @@ -8,16 +8,6 @@ import { buildHeroSrcset, getPhotoPath, getRelativePath, getSubgalleryThumbnailP import type { GalleryData, GallerySection, MediaFile, SubGallery } from '../gallery'; import type { ResolvedGalleryData, ResolvedHero, ResolvedImage, ResolvedSection, ResolvedSubGallery } from './types'; -/** - * Extracts thumbnail config from gallery data. - */ -function extractThumbnailConfigFromGallery(gallery: GalleryData): ThumbnailConfig { - return { - size: gallery.thumbnails?.size, - edge: gallery.thumbnails?.edge, - }; -} - /** * Resolve a single image with all paths computed. */ diff --git a/gallery/jest.config.cjs b/gallery/jest.config.cjs index 7433259..857723e 100644 --- a/gallery/jest.config.cjs +++ b/gallery/jest.config.cjs @@ -9,6 +9,7 @@ module.exports = { moduleNameMapper: { '^(\\.{1,2}/.*)\\.js$': '$1', '^@simple-photo-gallery/common$': '/../common/src/gallery.ts', + '^@simple-photo-gallery/common/theme$': '/../common/src/theme/index.ts', }, transform: { '^.+\\.tsx?$': [ diff --git a/gallery/src/modules/thumbnails/index.ts b/gallery/src/modules/thumbnails/index.ts index 937e017..839720e 100644 --- a/gallery/src/modules/thumbnails/index.ts +++ b/gallery/src/modules/thumbnails/index.ts @@ -1,7 +1,7 @@ import fs from 'node:fs'; import path from 'node:path'; -import { mergeThumbnailConfig } from '@simple-photo-gallery/common/theme'; +import { extractThumbnailConfigFromGallery, mergeThumbnailConfig } from '@simple-photo-gallery/common/theme'; import { LogLevels, type ConsolaInstance } from 'consola'; import { getFileMtime } from './utils'; @@ -15,21 +15,9 @@ import { getVideoDimensions, createVideoThumbnails } from '../../utils/video'; import type { ThumbnailOptions } from './types'; import type { CommandResultSummary } from '../telemetry/types'; -import type { GalleryData, MediaFile } from '@simple-photo-gallery/common'; +import type { MediaFile } from '@simple-photo-gallery/common'; import type { ThumbnailConfig } from '@simple-photo-gallery/common/theme'; -/** - * Extracts thumbnail config from gallery data. - * @param galleryData - The gallery data object - * @returns ThumbnailConfig with values from gallery.json - */ -function extractThumbnailConfigFromGallery(galleryData: GalleryData): ThumbnailConfig { - return { - size: galleryData.thumbnails?.size, - edge: galleryData.thumbnails?.edge, - }; -} - /** * Processes an image file to create thumbnail and extract metadata * @param imagePath - Path to the image file diff --git a/gallery/tests/theme-config.test.ts b/gallery/tests/theme-config.test.ts new file mode 100644 index 0000000..b30aa18 --- /dev/null +++ b/gallery/tests/theme-config.test.ts @@ -0,0 +1,179 @@ +import { extractThumbnailConfigFromGallery, mergeThumbnailConfig } from '../../common/src/theme/config'; + +describe('Theme Configuration', () => { + describe('mergeThumbnailConfig', () => { + test('should prefer gallery config over theme config', () => { + const result = mergeThumbnailConfig({ size: 400, edge: 'width' }, { size: 300, edge: 'auto' }); + + expect(result.size).toBe(400); + expect(result.edge).toBe('width'); + }); + + test('should fall back to theme config when gallery config is empty', () => { + const result = mergeThumbnailConfig({}, { size: 350, edge: 'height' }); + + expect(result.size).toBe(350); + expect(result.edge).toBe('height'); + }); + + test('should use defaults when both configs are empty', () => { + const result = mergeThumbnailConfig({}, {}); + + expect(result.size).toBe(300); + expect(result.edge).toBe('auto'); + }); + + test('should use defaults when no configs are provided', () => { + const result = mergeThumbnailConfig(); + + expect(result.size).toBe(300); + expect(result.edge).toBe('auto'); + }); + + test('should merge partial gallery config with theme config', () => { + const result = mergeThumbnailConfig({ size: 500 }, { size: 300, edge: 'height' }); + + expect(result.size).toBe(500); + expect(result.edge).toBe('height'); + }); + + test('should merge partial gallery config with defaults', () => { + const result = mergeThumbnailConfig({ edge: 'width' }, {}); + + expect(result.size).toBe(300); + expect(result.edge).toBe('width'); + }); + + test('should handle undefined gallery config', () => { + const result = mergeThumbnailConfig(undefined, { size: 400, edge: 'height' }); + + expect(result.size).toBe(400); + expect(result.edge).toBe('height'); + }); + + test('should handle undefined theme config', () => { + const result = mergeThumbnailConfig({ size: 250, edge: 'auto' }); + + expect(result.size).toBe(250); + expect(result.edge).toBe('auto'); + }); + + test('should handle both configs as undefined', () => { + const result = mergeThumbnailConfig(); + + expect(result.size).toBe(300); + expect(result.edge).toBe('auto'); + }); + + test('should respect the three-tier hierarchy', () => { + const galleryConfig = { size: 450 }; + const themeConfig = { size: 350, edge: 'height' as const }; + + const result = mergeThumbnailConfig(galleryConfig, themeConfig); + + expect(result.size).toBe(450); + expect(result.edge).toBe('height'); + }); + }); + + describe('extractThumbnailConfigFromGallery', () => { + test('should extract thumbnail config from gallery data', () => { + const gallery = { + thumbnails: { + size: 400, + edge: 'width' as const, + }, + }; + + const result = extractThumbnailConfigFromGallery(gallery); + + expect(result.size).toBe(400); + expect(result.edge).toBe('width'); + }); + + test('should return empty config when thumbnails is undefined', () => { + const gallery = {}; + + const result = extractThumbnailConfigFromGallery(gallery); + + expect(result.size).toBeUndefined(); + expect(result.edge).toBeUndefined(); + }); + + test('should extract partial thumbnail config', () => { + const gallery = { + thumbnails: { + size: 350, + }, + }; + + const result = extractThumbnailConfigFromGallery(gallery); + + expect(result.size).toBe(350); + expect(result.edge).toBeUndefined(); + }); + + test('should extract only edge when size is not specified', () => { + const gallery = { + thumbnails: { + edge: 'height' as const, + }, + }; + + const result = extractThumbnailConfigFromGallery(gallery); + + expect(result.size).toBeUndefined(); + expect(result.edge).toBe('height'); + }); + + test('should handle empty thumbnails object', () => { + const gallery = { + thumbnails: {}, + }; + + const result = extractThumbnailConfigFromGallery(gallery); + + expect(result.size).toBeUndefined(); + expect(result.edge).toBeUndefined(); + }); + }); + + describe('Integration: Extract + Merge', () => { + test('should correctly merge extracted gallery config with theme config', () => { + const gallery = { + thumbnails: { + size: 500, + }, + }; + + const themeConfig = { size: 300, edge: 'height' as const }; + + const galleryConfig = extractThumbnailConfigFromGallery(gallery); + const result = mergeThumbnailConfig(galleryConfig, themeConfig); + + expect(result.size).toBe(500); + expect(result.edge).toBe('height'); + }); + + test('should use theme config when gallery has no thumbnail settings', () => { + const gallery = {}; + const themeConfig = { size: 400, edge: 'width' as const }; + + const galleryConfig = extractThumbnailConfigFromGallery(gallery); + const result = mergeThumbnailConfig(galleryConfig, themeConfig); + + expect(result.size).toBe(400); + expect(result.edge).toBe('width'); + }); + + test('should use defaults when neither gallery nor theme has settings', () => { + const gallery = {}; + + const galleryConfig = extractThumbnailConfigFromGallery(gallery); + const result = mergeThumbnailConfig(galleryConfig); + + expect(result.size).toBe(300); + expect(result.edge).toBe('auto'); + }); + }); +}); From e626be22570e96b17fffee52070c825b17c24f91 Mon Sep 17 00:00:00 2001 From: rustoma Date: Sat, 24 Jan 2026 06:41:40 +0100 Subject: [PATCH 43/55] docs: update theme configuration documentation to clarify loading priority and user overrides --- common/src/theme/loader.ts | 13 ++++++++++--- docs/configuration.md | 2 ++ 2 files changed, 12 insertions(+), 3 deletions(-) diff --git a/common/src/theme/loader.ts b/common/src/theme/loader.ts index f46f64d..9ce9e48 100644 --- a/common/src/theme/loader.ts +++ b/common/src/theme/loader.ts @@ -18,9 +18,16 @@ export interface LoadGalleryDataOptions { /** * Load theme configuration from themeConfig.json file. * - * Searches for themeConfig.json in the following locations: - * 1. Current working directory (process.cwd()) - * 2. Provided themePath parameter + * 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 diff --git a/docs/configuration.md b/docs/configuration.md index 1c60188..6d7abd9 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -241,6 +241,8 @@ Markdown formatting is available in: Thumbnail generation and display can be configured through a hierarchical configuration system: +> **Migration Note:** If you're upgrading from an older version that used `thumbnailSize` (a number field), this has been replaced with a `thumbnails` object containing `size` and `edge` properties. Your existing `thumbnailSize` value will be automatically migrated to `thumbnails.size` when you run any gallery command. + 1. **Gallery-level configuration** (highest priority) - Set in `gallery.json` 2. **Theme-level configuration** - Set in theme's `themeConfig.json` file 3. **Built-in defaults** (lowest priority) - 300px on auto (longer edge) From 5001505ea7dec806ce1aa800561cc030df4f4fbb Mon Sep 17 00:00:00 2001 From: rustoma Date: Tue, 27 Jan 2026 06:45:55 +0100 Subject: [PATCH 44/55] docs: remove outdated theme module documentation to streamline README --- common/README.md | 808 ----------------------------------------------- 1 file changed, 808 deletions(-) diff --git a/common/README.md b/common/README.md index bfa3302..cb4f62f 100644 --- a/common/README.md +++ b/common/README.md @@ -14,811 +14,3 @@ npm install @simple-photo-gallery/common - `./theme` - Theme utilities for data loading and resolution - `./client` - Browser-side utilities (PhotoSwipe, blurhash, CSS) - `./styles/photoswipe` - PhotoSwipe CSS bundle - ---- - -## Theme Module (`@simple-photo-gallery/common/theme`) - -Theme utilities for loading and transforming gallery data. - -### Data Loading - -#### `loadGalleryData(path, options?)` - -Loads and optionally validates gallery.json. - -```typescript -function loadGalleryData(galleryJsonPath?: string, options?: LoadGalleryDataOptions): GalleryData; -``` - -**Parameters:** - -- `galleryJsonPath` (optional): Path to gallery.json file. Defaults to `'./gallery.json'` -- `options` (optional): - - `validate?: boolean` - Enable Zod schema validation (default: `false`) - -**Returns:** Raw `GalleryData` object - -**Throws:** Error if file cannot be read, parsed, or fails validation - -**Example:** - -```typescript -import { loadGalleryData } from '@simple-photo-gallery/common/theme'; - -// Basic usage (no validation) -const gallery = loadGalleryData('./gallery.json'); - -// With schema validation -const gallery = loadGalleryData('./gallery.json', { validate: true }); -``` - ---- - -#### `loadThemeConfig(themePath?)` - -Loads theme configuration from themeConfig.json file. - -```typescript -function loadThemeConfig(themePath?: string): ThumbnailConfig | undefined; -``` - -**Parameters:** - -- `themePath` (optional): Path to the theme directory containing themeConfig.json - -**Returns:** `ThumbnailConfig` object with thumbnail settings, or `undefined` if not found - -**Searches in order:** - -1. Current working directory (`process.cwd()/themeConfig.json`) -2. Provided `themePath` parameter (`themePath/themeConfig.json`) - -**Example:** - -```typescript -import path from 'node:path'; -import { loadThemeConfig } from '@simple-photo-gallery/common/theme'; - -// Load from theme directory -const themePath = path.resolve(import.meta.dirname, '../..'); -const themeConfig = loadThemeConfig(themePath); - -// Use in data resolution -const gallery = await resolveGalleryData(raw, { - galleryJsonPath: './gallery.json', - themeConfig, -}); -``` - -**Theme Configuration Structure:** - -```json -{ - "thumbnails": { - "size": 300, - "edge": "height" - } -} -``` - ---- - -#### `resolveGalleryData(data, options?)` - -Transforms raw data into fully-resolved structure with pre-computed paths and parsed markdown. - -```typescript -async function resolveGalleryData(data: GalleryData, options?: ResolveGalleryDataOptions): Promise; -``` - -**Parameters:** - -- `data`: Raw `GalleryData` object (from `loadGalleryData()`) -- `options` (optional): - - `galleryJsonPath?: string` - Path to gallery.json, enables relative path resolution for sub-galleries - - `themeConfig?: ThumbnailConfig` - Theme-level thumbnail configuration (from `loadThemeConfig()`) - -**Returns:** `ResolvedGalleryData` with: - -- Pre-computed image and thumbnail paths -- Built responsive image srcsets for hero -- Parsed markdown descriptions as HTML -- Computed properties for sub-galleries -- Resolved thumbnail configuration (merged from gallery.json, theme config, and defaults) - -**Example:** - -```typescript -import path from 'node:path'; -import { loadGalleryData, loadThemeConfig, resolveGalleryData } from '@simple-photo-gallery/common/theme'; - -const raw = loadGalleryData('./gallery.json', { validate: true }); - -// Load theme config (optional, for theme-level thumbnail defaults) -const themePath = path.resolve(import.meta.dirname, '../..'); -const themeConfig = loadThemeConfig(themePath); - -const gallery = await resolveGalleryData(raw, { - galleryJsonPath: './gallery.json', - themeConfig, -}); - -// Access resolved data -console.log(gallery.hero.src); // Pre-computed hero path -console.log(gallery.hero.srcsets); // Responsive srcsets -console.log(gallery.sections[0].parsedDescription); // HTML from markdown -``` - ---- - -### Path Utilities - -#### `getPhotoPath(filename, baseUrl?, url?)` - -Resolves media file path with optional base URL. - -```typescript -function getPhotoPath(filename: string, baseUrl?: string, url?: string): string; -``` - ---- - -#### `getThumbnailPath(path, baseUrl?, thumbBaseUrl?)` - -Resolves thumbnail path with optional base URL. - -```typescript -function getThumbnailPath(path: string, baseUrl?: string, thumbBaseUrl?: string): string; -``` - ---- - -#### `buildHeroSrcset(variants?, sizes, basePath, basename, orientation, format, useDefault?)` - -Builds responsive image srcset string for hero images. - -```typescript -function buildHeroSrcset( - variants: string[] | undefined, - sizes: readonly number[], - basePath: string, - basename: string, - orientation: 'landscape' | 'portrait', - format: 'avif' | 'jpg', - useDefaultPaths: boolean, -): string; -``` - ---- - -#### `getRelativePath(to, from)` - -Computes relative path between two locations. - -```typescript -function getRelativePath(to: string, from: string): string; -``` - ---- - -#### `getSubgalleryThumbnailPath(headerImage)` - -Computes thumbnail path for sub-gallery header images. - -```typescript -function getSubgalleryThumbnailPath(headerImage: string): string; -``` - ---- - -### Utilities - -#### `renderMarkdown(markdown)` - -Parses markdown to HTML with limited formatting (no headings, images, HTML, or tables). - -```typescript -async function renderMarkdown(markdown: string): Promise; -``` - -**Example:** - -```typescript -import { renderMarkdown } from '@simple-photo-gallery/common/theme'; - -const html = await renderMarkdown('**Bold** and *italic* text'); -// Returns: '

Bold and italic text

' -``` - ---- - -#### `preventEmptyContentFiles()` - -Astro integration that removes empty content collection files after build. - -```typescript -function preventEmptyContentFiles(): AstroIntegration; -``` - -**Example:** - -```typescript -// In astro.config.ts -import { preventEmptyContentFiles } from '@simple-photo-gallery/common/theme'; - -export default defineConfig({ - integrations: [preventEmptyContentFiles()], -}); -``` - ---- - -### Constants - -#### `LANDSCAPE_SIZES` - -Responsive image sizes for landscape-oriented hero images. - -```typescript -const LANDSCAPE_SIZES: readonly number[] = [400, 800, 1200, 1600, 2400]; -``` - -#### `PORTRAIT_SIZES` - -Responsive image sizes for portrait-oriented hero images. - -```typescript -const PORTRAIT_SIZES: readonly number[] = [400, 800, 1200]; -``` - ---- - -### Types - -#### `ResolvedGalleryData` - -Fully resolved gallery structure ready for rendering. - -```typescript -interface ResolvedGalleryData { - hero: ResolvedHero; - sections: ResolvedSection[]; - subGalleries?: ResolvedSubGallery[]; - thumbnails?: Required; // Resolved thumbnail configuration - // ... other metadata (url, metadata, analyticsScript, etc.) -} -``` - -#### `ResolvedHero` - -Hero section with pre-computed srcsets and paths. - -```typescript -interface ResolvedHero { - title: string; - description: string; - parsedDescription: string; - src: string; - blurHash?: string; - srcsets: { - portraitAvif: string; - portraitJpg: string; - landscapeAvif: string; - landscapeJpg: string; - }; - // ... other properties -} -``` - -#### `ResolvedSection` - -Gallery section with resolved image paths and parsed markdown. - -```typescript -interface ResolvedSection { - title?: string; - description?: string; - parsedDescription: string; - images: ResolvedImage[]; -} -``` - -#### `ResolvedImage` - -Individual image with computed paths and optional thumbnail srcsets. - -```typescript -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; -} -``` - -#### `ResolvedSubGallery` - -Sub-gallery with computed thumbnail paths. - -```typescript -interface ResolvedSubGallery { - title: string; - headerImage: string; - path: string; - thumbnailPath: string; - resolvedPath?: string; -} -``` - -#### `LoadGalleryDataOptions` - -Options for `loadGalleryData()`. - -```typescript -interface LoadGalleryDataOptions { - validate?: boolean; -} -``` - -#### `ResolveGalleryDataOptions` - -Options for `resolveGalleryData()`. - -```typescript -interface ResolveGalleryDataOptions { - galleryJsonPath?: string; - themeConfig?: ThumbnailConfig; -} -``` - -#### `ThumbnailConfig` - -Thumbnail configuration settings. - -```typescript -interface ThumbnailConfig { - size?: number; // Thumbnail size in pixels (default: 300) - edge?: 'auto' | 'width' | 'height'; // How size is applied (default: 'auto') -} -``` - -**Edge Options:** - -- `'auto'`: Applied to longer edge (default behavior) -- `'width'`: Applied to width (good for masonry layouts) -- `'height'`: Applied to height (good for row-based layouts) - ---- - -## Client Module (`@simple-photo-gallery/common/client`) - -Browser-side utilities for client-side functionality. - -### Blurhash - -#### `decodeAllBlurhashes()` - -Decodes all blurhash canvases on the page (elements with `data-blurhash` attribute). - -```typescript -function decodeAllBlurhashes(): void; -``` - -**Example:** - -```typescript -import { decodeAllBlurhashes } from '@simple-photo-gallery/common/client'; - -// In your client-side script -decodeAllBlurhashes(); -``` - -**HTML:** - -```html - -``` - ---- - -#### `decodeBlurhashToCanvas(canvas, blurhash)` - -Decodes a single blurhash to a canvas element. - -```typescript -function decodeBlurhashToCanvas(canvas: HTMLCanvasElement, blurhash: string): void; -``` - ---- - -### PhotoSwipe - -#### `createGalleryLightbox(options?)` - -Creates a configured PhotoSwipe lightbox instance with video support. - -```typescript -function createGalleryLightbox(options?: GalleryLightboxOptions): PhotoSwipeLightbox; -``` - -**Parameters:** - -- `options` (optional): - - `gallery?: string` - Gallery element selector (default: `'#gallery'`) - - `children?: string` - Child elements selector (default: `'a'`) - - `pswpModule?: typeof PhotoSwipe` - PhotoSwipe module (default: imported PhotoSwipe) - - `videoPlugin?: VideoPluginOptions` - Video plugin configuration - -**Returns:** Configured PhotoSwipe lightbox instance (call `.init()` to activate) - -**Example:** - -```typescript -import { createGalleryLightbox } from '@simple-photo-gallery/common/client'; - -const lightbox = createGalleryLightbox({ - gallery: '#my-gallery', - children: 'a.gallery-item', -}); - -lightbox.init(); -``` - ---- - -#### `PhotoSwipeVideoPlugin` - -Plugin class for video support in PhotoSwipe lightbox. - -```typescript -class PhotoSwipeVideoPlugin { - constructor(lightbox: PhotoSwipeLightbox, options?: VideoPluginOptions); -} -``` - -**Usage:** Automatically included when using `createGalleryLightbox()`. - ---- - -### Hero Utilities - -#### `initHeroImageFallback(options?)` - -Initializes hero image fallback behavior (transitions from blur hash to actual image). - -```typescript -function initHeroImageFallback(options?: HeroImageFallbackOptions): void; -``` - -**Parameters:** - -- `options` (optional): - - `heroSelector?: string` - Hero element selector (default: `'.hero'`) - - `imageSelector?: string` - Hero image selector (default: `'.hero__image'`) - -**Example:** - -```typescript -import { initHeroImageFallback } from '@simple-photo-gallery/common/client'; - -initHeroImageFallback({ - heroSelector: '.my-hero', - imageSelector: '.my-hero img', -}); -``` - ---- - -### CSS Utilities - -#### `setCSSVar(name, value, element?)` - -Sets a CSS custom property value. - -```typescript -function setCSSVar(name: string, value: string, element?: HTMLElement): void; -``` - -**Example:** - -```typescript -import { setCSSVar } from '@simple-photo-gallery/common/client'; - -// Set on document root -setCSSVar('--primary-color', '#007bff'); - -// Set on specific element -const hero = document.querySelector('.hero'); -setCSSVar('--hero-bg', '#000', hero); -``` - ---- - -#### `parseColor(color)` - -Parses a color string to RGB array. - -```typescript -function parseColor(color: string): [number, number, number] | null; -``` - -**Supports:** Hex colors (`#fff`, `#ffffff`) and RGB strings (`rgb(255, 0, 0)`) - ---- - -#### `normalizeHex(hex)` - -Normalizes a hex color to 6-character format. - -```typescript -function normalizeHex(hex: string): string; -``` - -**Example:** - -```typescript -normalizeHex('#fff'); // Returns: '#ffffff' -normalizeHex('#ffffff'); // Returns: '#ffffff' -``` - ---- - -#### `deriveOpacityColor(baseColor, opacity)` - -Derives an RGBA color from a base color and opacity. - -```typescript -function deriveOpacityColor(baseColor: string, opacity: number): string; -``` - -**Example:** - -```typescript -import { deriveOpacityColor } from '@simple-photo-gallery/common/client'; - -const semiTransparent = deriveOpacityColor('#007bff', 0.5); -// Returns: 'rgba(0, 123, 255, 0.5)' -``` - ---- - -## Gallery Module (`@simple-photo-gallery/common`) - -Core gallery types and Zod validation schemas. - -### Types - -#### `GalleryData` - -Raw gallery structure as stored in gallery.json. - -```typescript -interface GalleryData { - title: string; - description: string; - headerImage: string; - headerImageBlurHash?: string; - headerImageVariants?: HeaderImageVariants; - mediaBasePath?: string; - mediaBaseUrl?: string; - thumbsBaseUrl?: string; - url?: string; - analyticsScript?: string; - ctaBanner?: boolean; - thumbnailSize?: number; - metadata: GalleryMetadata; - sections: GallerySection[]; - subGalleries?: SubGallery[]; -} -``` - -#### `GallerySection` - -Gallery section with images. - -```typescript -interface GallerySection { - title?: string; - description?: string; - images: MediaFile[]; -} -``` - -#### `MediaFile` - -Image or video with metadata. - -```typescript -interface MediaFile { - type: 'image' | 'video'; - filename: string; - alt?: string; - width: number; - height: number; - url?: string; - thumbnail?: Thumbnail; -} -``` - -#### `GalleryMetadata` - -SEO and social metadata. - -```typescript -interface GalleryMetadata { - image?: string; - imageWidth?: number; - imageHeight?: number; - ogUrl?: string; - ogType?: string; - ogSiteName?: string; - twitterSite?: string; - twitterCreator?: string; - author?: string; - keywords?: string; - canonicalUrl?: string; - robots?: string; -} -``` - -#### `SubGallery` - -Nested gallery reference. - -```typescript -interface SubGallery { - title: string; - headerImage: string; - path: string; -} -``` - -#### `Thumbnail` - -Thumbnail metadata with blur hash. - -```typescript -interface Thumbnail { - path: string; - pathRetina: string; - width: number; - height: number; - blurHash?: string; - baseUrl?: string; -} -``` - -#### `HeaderImageVariants` - -Responsive image variant definitions for header images. - -```typescript -interface HeaderImageVariants { - landscape?: { - avif?: string[]; - jpg?: string[]; - }; - portrait?: { - avif?: string[]; - jpg?: string[]; - }; -} -``` - ---- - -### Schemas - -All types have corresponding Zod validation schemas: - -- `GalleryDataSchema` - Validates complete gallery.json structure -- `GallerySectionSchema` - Validates individual sections -- `MediaFileSchema` - Validates image/video entries -- `GalleryMetadataSchema` - Validates metadata object -- `SubGallerySchema` - Validates sub-gallery entries -- `ThumbnailSchema` - Validates thumbnail metadata -- `HeaderImageVariantsSchema` - Validates responsive image variants - -**Example:** - -```typescript -import { GalleryDataSchema } from '@simple-photo-gallery/common'; - -const result = GalleryDataSchema.safeParse(data); -if (result.success) { - console.log('Valid gallery data:', result.data); -} else { - console.error('Validation errors:', result.error); -} -``` - ---- - -## Example Theme Setup - -### Basic Astro Page - -```typescript ---- -// src/pages/index.astro -import { loadGalleryData, resolveGalleryData } from '@simple-photo-gallery/common/theme'; - -const galleryJsonPath = import.meta.env.GALLERY_JSON_PATH || './gallery.json'; -const raw = loadGalleryData(galleryJsonPath, { validate: true }); -const gallery = await resolveGalleryData(raw, { galleryJsonPath }); - -// Access resolved data -const { hero, sections } = gallery; ---- - - - - {hero.title} - - -
- - - - {hero.title} - -
-
- - {sections.map((section) => ( -
-

{section.title}

-
- {section.images.map((img) => ( - - {img.alt - - ))} -
- ))} - - -``` - -### Client-Side Script - -```typescript -// src/scripts/gallery.ts -import { decodeAllBlurhashes, createGalleryLightbox, initHeroImageFallback } from '@simple-photo-gallery/common/client'; - -// Decode blurhash placeholders -decodeAllBlurhashes(); - -// Initialize hero image fallback -initHeroImageFallback(); - -// Setup PhotoSwipe lightbox -const lightbox = createGalleryLightbox({ - gallery: '#gallery', - children: 'a', -}); -lightbox.init(); -``` - ---- - -## See Also - -- [Custom Themes Guide](../docs/themes.md) - Complete theme development guide -- [Architecture](../docs/architecture.md) - System design and implementation details -- [Modern Theme Source](../themes/modern/) - Reference implementation -- [Commands Reference](../docs/commands/README.md) - CLI commands documentation From a2a2b8e5e182ca6f1bbbb8d5741730b0355af5bb Mon Sep 17 00:00:00 2001 From: rustoma Date: Tue, 27 Jan 2026 18:49:28 +0100 Subject: [PATCH 45/55] docs: expand configuration documentation to include theme and thumbnail settings, clarifying CLI options and hierarchy --- docs/commands/build.md | 29 ++++++++++-------- docs/commands/create-theme.md | 6 ++-- docs/commands/init.md | 35 ++++++++++++--------- docs/commands/thumbnails.md | 24 ++++++++++----- docs/configuration.md | 58 ++++++++++++++++++++++++++++------- 5 files changed, 106 insertions(+), 46 deletions(-) diff --git a/docs/commands/build.md b/docs/commands/build.md index efcf176..7c0bf82 100644 --- a/docs/commands/build.md +++ b/docs/commands/build.md @@ -14,18 +14,20 @@ If you have created the gallery in a different folder from the photos folder, th ## Options -| Option | Description | Default | -| ----------------------------- | ------------------------------------------- | ------------------------------------ | -| `-g, --gallery ` | Path to gallery directory | Current directory | -| `-r, --recursive` | Build all galleries | `false` | -| `-b, --base-url ` | Base URL for external hosting | None | -| `-t, --thumbs-base-url ` | Base URL for external hosting of thumbnails | None | -| `--theme ` | Theme package name | `@simple-photo-gallery/theme-modern` | -| `--no-scan` | Do not scan for new photos | `true` | -| `--no-thumbnails` | Skip creating thumbnails | `true` | -| `-v, --verbose` | Show detailed output | | -| `-q, --quiet` | Only show warnings/errors | | -| `-h, --help` | Show command help | | +| Option | Description | Default | +| ----------------------------- | -------------------------------------------------- | --------------------------------------- | +| `-g, --gallery ` | Path to gallery directory | Current directory | +| `-r, --recursive` | Build all galleries | `false` | +| `-b, --base-url ` | Base URL for external hosting | None | +| `-t, --thumbs-base-url ` | Base URL for external hosting of thumbnails | None | +| `--theme ` | Theme package name or local path | gallery.json theme or `theme-modern` | +| `--thumbnail-size ` | Override thumbnail size in pixels | From config hierarchy | +| `--thumbnail-edge ` | Override size mode: auto, width, or height | From config hierarchy | +| `--no-scan` | Do not scan for new photos | `true` | +| `--no-thumbnails` | Skip creating thumbnails | `true` | +| `-v, --verbose` | Show detailed output | | +| `-q, --quiet` | Only show warnings/errors | | +| `-h, --help` | Show command help | | ## Examples @@ -56,6 +58,9 @@ spg build --theme @your-org/your-private-theme # Build with a local theme (path) spg build --theme ./themes/my-local-theme + +# Build with custom thumbnail settings (overrides gallery.json and theme) +spg build --thumbnail-size 400 --thumbnail-edge height ``` ## Custom Themes diff --git a/docs/commands/create-theme.md b/docs/commands/create-theme.md index 9058cba..6a83827 100644 --- a/docs/commands/create-theme.md +++ b/docs/commands/create-theme.md @@ -8,11 +8,13 @@ spg create-theme [options] ## How it works -The command creates a new theme by copying the base theme template (bundled with the package) and customizing it with your theme name. The generated theme includes: +The command creates a new theme by copying the base theme template (bundled with the package) and customizing it with your theme name. The generated theme is a **1:1 copy of the modern theme** that users are familiar with, including: - `package.json`, `astro.config.ts`, `tsconfig.json` - `src/pages/index.astro` (main entry point) -- Basic layouts/components and helper utilities +- Full-featured components (Hero, GallerySection, PhotoSwipe lightbox, SubGalleries, CTA banner, Footer) +- Responsive layouts with blurhash placeholders and AVIF/JPG support +- Query parameter customization utilities - All configuration files (ESLint, Prettier, etc.) The command: diff --git a/docs/commands/init.md b/docs/commands/init.md index 2638285..51c25b5 100644 --- a/docs/commands/init.md +++ b/docs/commands/init.md @@ -14,30 +14,31 @@ This command initializes a new gallery by scanning a folder (and optionally its - Gallery description - Header image (selected from your photos) - URL where the gallery will be hosted -- Thumbnail size (in pixels) - optional, press Enter to use theme/default settings -- Thumbnail edge mode (auto/width/height) - optional, press Enter to use theme/default settings All of these settings can later be edited in the `gallery.json` file. > **Note:** The URL is important if you want the automatically generated social media images to work correctly, as it needs to be an absolute URL. -> **Tip:** For thumbnail settings, you can press Enter to skip the prompts. This allows the [configuration hierarchy](../configuration.md#thumbnail-configuration) to work: gallery.json → themeConfig.json → built-in defaults (300px, auto edge). +> **Tip:** Theme and thumbnail settings can be specified via CLI flags (`--theme`, `--thumbnail-size`, `--thumbnail-edge`) for users who know what they want upfront. These are stored in `gallery.json` and follow the [configuration hierarchy](../configuration.md#thumbnail-configuration): CLI → gallery.json → themeConfig.json → built-in defaults. After that, the command will create a `gallery` folder and a `gallery.json` file in it. The `gallery.json` file contains all the information about the gallery, including the title, description, header image, URL, thumbnail settings (if specified), and all images and videos in the gallery. ## Options -| Option | Description | Default | -| ---------------------- | ------------------------------------------------ | --------------------- | -| `-p, --photos ` | Path to folder containing photos | Current directory | -| `-g, --gallery ` | Where to create the gallery | Same as photos folder | -| `-r, --recursive` | Create galleries from subdirectories | `false` | -| `-d, --default` | Use default settings (skip prompts) | `false` | -| `-f, --force` | Force override existing galleries without asking | `false` | -| `--cta-banner` | Add a Simple Photo Gallery CTA banner to the gallery | `false` | -| `-v, --verbose` | Show detailed output | | -| `-q, --quiet` | Only show warnings/errors | | -| `-h, --help` | Show command help | | +| Option | Description | Default | +| ----------------------------- | ---------------------------------------------------------- | --------------------- | +| `-p, --photos ` | Path to folder containing photos | Current directory | +| `-g, --gallery ` | Where to create the gallery | Same as photos folder | +| `-r, --recursive` | Create galleries from subdirectories | `false` | +| `-d, --default` | Use default settings (skip prompts) | `false` | +| `-f, --force` | Force override existing galleries without asking | `false` | +| `--cta-banner` | Add a Simple Photo Gallery CTA banner to the gallery | `false` | +| `--theme ` | Theme to store in gallery.json | None | +| `--thumbnail-size ` | Thumbnail size in pixels to store in gallery.json | Theme/default (300) | +| `--thumbnail-edge ` | Size application mode: auto, width, or height | Theme/default (auto) | +| `-v, --verbose` | Show detailed output | | +| `-q, --quiet` | Only show warnings/errors | | +| `-h, --help` | Show command help | | ## Examples @@ -62,6 +63,12 @@ spg init -f # Combine options spg init -r -d -f + +# Initialize with a specific theme and thumbnail settings +spg init --theme @simple-photo-gallery/theme-modern --thumbnail-size 400 + +# Initialize with custom thumbnail edge mode +spg init --thumbnail-size 300 --thumbnail-edge height ``` ## Creating the gallery in a folder other than the photos folder diff --git a/docs/commands/thumbnails.md b/docs/commands/thumbnails.md index 331ae30..78414da 100644 --- a/docs/commands/thumbnails.md +++ b/docs/commands/thumbnails.md @@ -10,6 +10,8 @@ spg thumbnails [options] The command will go through all media files and generate thumbnails with suitable resolutions for the gallery. It will also update the `gallery.json` file with the new thumbnail paths. +Thumbnail configuration follows the [configuration hierarchy](../configuration.md#thumbnail-configuration): CLI options → gallery.json → themeConfig.json → built-in defaults (300px, auto edge). If your gallery.json specifies a theme, the theme's thumbnail settings will be loaded as a fallback. + Thumbnails for videos require FFmpeg to be installed so it can extract the first frame of the video. You can install it via: - **macOS:** `brew install ffmpeg` @@ -20,13 +22,15 @@ Thumbnails for videos require FFmpeg to be installed so it can extract the first ## Options -| Option | Description | Default | -| ---------------------- | ------------------------- | ----------------- | -| `-g, --gallery ` | Path to gallery directory | Current directory | -| `-r, --recursive` | Process subdirectories | `false` | -| `-v, --verbose` | Show detailed output | | -| `-q, --quiet` | Only show warnings/errors | | -| `-h, --help` | Show command help | | +| Option | Description | Default | +| ----------------------------- | ------------------------------------------------- | --------------------- | +| `-g, --gallery ` | Path to gallery directory | Current directory | +| `-r, --recursive` | Process subdirectories | `false` | +| `--thumbnail-size ` | Override thumbnail size in pixels | From config hierarchy | +| `--thumbnail-edge ` | Override size mode: auto, width, or height | From config hierarchy | +| `-v, --verbose` | Show detailed output | | +| `-q, --quiet` | Only show warnings/errors | | +| `-h, --help` | Show command help | | ## Examples @@ -39,4 +43,10 @@ spg thumbnails -g /path/to/gallery # Process all galleries recursively npx simple-photo-gallery@latest thumbnails -r + +# Override thumbnail size via CLI +spg thumbnails --thumbnail-size 400 + +# Override both size and edge mode +spg thumbnails --thumbnail-size 250 --thumbnail-edge height ``` diff --git a/docs/configuration.md b/docs/configuration.md index 6d7abd9..7381836 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -29,6 +29,31 @@ Additionally, the following parameters are automatically generated, but you can - `ogImageWidth` - The width of the image - `ogImageHeight` - The height of the image +## Theme + +You can specify the theme to use for your gallery by setting the `theme` field in `gallery.json`. This allows each gallery to use a different theme without needing to specify it via CLI each time. + +```json +{ + "title": "My Gallery", + "theme": "@simple-photo-gallery/theme-modern" +} +``` + +The theme can be specified as: +- An npm package name (e.g., `@simple-photo-gallery/theme-modern`) +- A local path (e.g., `./themes/my-custom-theme`) + +### Theme Resolution Priority + +When building a gallery, the theme is resolved in this order: + +1. **CLI option** (highest priority) - `--theme` flag +2. **gallery.json** - The `theme` field in your gallery configuration +3. **Default theme** (lowest priority) - `@simple-photo-gallery/theme-modern` + +When you specify a theme via the CLI `--theme` flag, it is saved to `gallery.json` for future builds. + ## Sections Sections can be used to group your photos with their own titles and descriptions. This is useful if you have a large gallery and want to split it into smaller sections. @@ -243,19 +268,22 @@ Thumbnail generation and display can be configured through a hierarchical config > **Migration Note:** If you're upgrading from an older version that used `thumbnailSize` (a number field), this has been replaced with a `thumbnails` object containing `size` and `edge` properties. Your existing `thumbnailSize` value will be automatically migrated to `thumbnails.size` when you run any gallery command. -1. **Gallery-level configuration** (highest priority) - Set in `gallery.json` -2. **Theme-level configuration** - Set in theme's `themeConfig.json` file -3. **Built-in defaults** (lowest priority) - 300px on auto (longer edge) +1. **CLI options** (highest priority) - Passed via `--thumbnail-size` and `--thumbnail-edge` flags +2. **Gallery-level configuration** - Set in `gallery.json` +3. **Theme-level configuration** - Set in theme's `themeConfig.json` file +4. **Built-in defaults** (lowest priority) - 300px on auto (longer edge) ### Configuration Hierarchy The thumbnail settings follow this priority order: ``` -gallery.json > themeConfig.json > built-in defaults +CLI options > gallery.json > themeConfig.json > built-in defaults ``` -This means if you specify thumbnail settings in `gallery.json`, those will be used. If not, the theme's `themeConfig.json` will be checked. If neither is set, the built-in defaults (300px, auto edge) will be used. +This means CLI options always take highest priority, followed by `gallery.json` settings. If not specified in either, the theme's `themeConfig.json` will be checked. If neither is set, the built-in defaults (300px, auto edge) will be used. + +When you provide thumbnail settings via CLI flags to the `init`, `thumbnails`, or `build` commands, those settings are saved to `gallery.json` for future builds. ### Gallery-level Configuration @@ -303,14 +331,22 @@ When thumbnails are configured, they also control the display size in themes: - **Modern theme**: `thumbnails.size` becomes the row height (e.g., `size: 200` sets `--row-height: 200px`) - **Default behavior** (no thumbnails config): Uses responsive breakpoints (96px on mobile, scaling up to 160px on desktop) -### Interactive Configuration +### CLI Configuration -When running `gallery init`, you'll be prompted to configure thumbnail settings. You can: -- Enter a custom size (in pixels) -- Choose how the size is applied (auto/width/height) -- Press Enter to skip and use theme/default settings +You can configure thumbnail settings when running `gallery init`, `gallery thumbnails`, or `gallery build` by using the CLI flags: + +```bash +# Set thumbnail size and edge during init +gallery init --thumbnail-size 400 --thumbnail-edge height + +# Override settings when generating thumbnails +gallery thumbnails --thumbnail-size 300 --thumbnail-edge auto + +# Override settings when building +gallery build --thumbnail-size 400 --thumbnail-edge height +``` -Only explicitly set values will be saved to `gallery.json`, keeping the file clean and allowing the configuration hierarchy to work properly. +When provided via CLI, these settings are saved to `gallery.json` for future builds, keeping the configuration hierarchy consistent. ## Header image variants From 8e54a6fef91e3eb7390825c29748e3780091aa26 Mon Sep 17 00:00:00 2001 From: rustoma Date: Tue, 27 Jan 2026 18:51:09 +0100 Subject: [PATCH 46/55] feat: implement new theme components and enhance README documentation for gallery customization --- .../templates/base/README_BASE.md | 39 +++- .../base/src/components/GalleryItem.astro | 57 ------ .../templates/base/src/components/Hero.astro | 172 ------------------ .../src/components/container/Container.astro | 10 + .../base/src/components/cta/CtaBanner.astro | 101 ++++++++++ .../base/src/components/footer/Footer.astro | 43 +++++ .../gallery-section/GallerySection.astro | 71 ++++++++ .../GallerySectionHeader.astro | 41 +++++ .../gallery-section/GallerySectionItem.astro | 97 ++++++++++ .../base/src/components/hero/Hero.astro | 141 ++++++++++++++ .../hero/HeroScrollToGalleryBtn.astro | 77 ++++++++ .../src/components/lightbox/PhotoSwipe.astro | 13 ++ .../sub-galleries/SubGalleries.astro | 129 +++++++++++++ .../templates/base/src/layouts/MainHead.astro | 147 ++++++++++++--- .../base/src/layouts/MainLayout.astro | 102 ++++++++++- .../templates/base/src/pages/index.astro | 105 ++++------- .../templates/base/themeConfig.json | 4 +- 17 files changed, 1015 insertions(+), 334 deletions(-) delete mode 100644 gallery/src/modules/create-theme/templates/base/src/components/GalleryItem.astro delete mode 100644 gallery/src/modules/create-theme/templates/base/src/components/Hero.astro create mode 100644 gallery/src/modules/create-theme/templates/base/src/components/container/Container.astro create mode 100644 gallery/src/modules/create-theme/templates/base/src/components/cta/CtaBanner.astro create mode 100644 gallery/src/modules/create-theme/templates/base/src/components/footer/Footer.astro create mode 100644 gallery/src/modules/create-theme/templates/base/src/components/gallery-section/GallerySection.astro create mode 100644 gallery/src/modules/create-theme/templates/base/src/components/gallery-section/GallerySectionHeader.astro create mode 100644 gallery/src/modules/create-theme/templates/base/src/components/gallery-section/GallerySectionItem.astro create mode 100644 gallery/src/modules/create-theme/templates/base/src/components/hero/Hero.astro create mode 100644 gallery/src/modules/create-theme/templates/base/src/components/hero/HeroScrollToGalleryBtn.astro create mode 100644 gallery/src/modules/create-theme/templates/base/src/components/lightbox/PhotoSwipe.astro create mode 100644 gallery/src/modules/create-theme/templates/base/src/components/sub-galleries/SubGalleries.astro diff --git a/gallery/src/modules/create-theme/templates/base/README_BASE.md b/gallery/src/modules/create-theme/templates/base/README_BASE.md index 0fd5512..92400a9 100644 --- a/gallery/src/modules/create-theme/templates/base/README_BASE.md +++ b/gallery/src/modules/create-theme/templates/base/README_BASE.md @@ -2,6 +2,15 @@ This is the {THEME_NAME_LOWER} theme for Simple Photo Gallery built with Astro. +This theme is a copy of the **modern theme** and includes all the production-ready components: + +- **Hero** - Full-screen header with responsive images (AVIF/JPG) and blurhash placeholders +- **Gallery Sections** - Flex-grow masonry layout with hover effects +- **PhotoSwipe Lightbox** - Full-featured image viewer with deep linking support +- **Sub-Galleries** - Navigation grid for nested galleries +- **CTA Banner** - Call-to-action component (optional via `ctaBanner: true` in gallery.json) +- **Footer** - Simple footer component + ## Getting Started 1. Install dependencies: @@ -10,7 +19,7 @@ This is the {THEME_NAME_LOWER} theme for Simple Photo Gallery built with Astro. yarn install ``` -2. Customize your theme in `src/pages/index.astro` +2. Customize your theme in `src/pages/index.astro` and the components in `src/components/` 3. Initialize a gallery (run from directory with your images): @@ -23,3 +32,31 @@ This is the {THEME_NAME_LOWER} theme for Simple Photo Gallery built with Astro. ```bash spg build --theme -g ``` + +## Directory Structure + +``` +src/ +├── pages/ +│ └── index.astro # Main entry point +├── layouts/ +│ ├── MainLayout.astro # Root HTML layout with global styles +│ └── MainHead.astro # Meta tags and image preloading +├── components/ +│ ├── container/ # Max-width wrapper +│ ├── cta/ # Call-to-action banner +│ ├── footer/ # Footer component +│ ├── gallery-section/ # Photo grid components +│ ├── hero/ # Hero header component +│ ├── lightbox/ # PhotoSwipe integration +│ └── sub-galleries/ # Sub-gallery navigation +└── utils/ + └── queryParams.ts # URL query parameter customizations +``` + +## Customization + +- **Styles**: Edit the ` diff --git a/gallery/src/modules/create-theme/templates/base/src/components/Hero.astro b/gallery/src/modules/create-theme/templates/base/src/components/Hero.astro deleted file mode 100644 index e8f1a6b..0000000 --- a/gallery/src/modules/create-theme/templates/base/src/components/Hero.astro +++ /dev/null @@ -1,172 +0,0 @@ ---- -import type { ResolvedHero } from '@simple-photo-gallery/common/theme'; - -interface Props { - hero: ResolvedHero; -} - -const { hero } = Astro.props; ---- - -{ - hero.headerImage ? ( -
-
- {hero.headerImageBlurHash && } - - {/* Portrait */} - - - - {/* Landscape */} - - - - {/* Fallback */} - - -
-
-
-

{hero.title}

- {hero.parsedDescription &&
} -
-
- ) : ( -
-

{hero.title}

- {hero.parsedDescription &&
} -
- ) -} - - - - diff --git a/gallery/src/modules/create-theme/templates/base/src/components/container/Container.astro b/gallery/src/modules/create-theme/templates/base/src/components/container/Container.astro new file mode 100644 index 0000000..5ceebef --- /dev/null +++ b/gallery/src/modules/create-theme/templates/base/src/components/container/Container.astro @@ -0,0 +1,10 @@ +
+ +
+ + diff --git a/gallery/src/modules/create-theme/templates/base/src/components/cta/CtaBanner.astro b/gallery/src/modules/create-theme/templates/base/src/components/cta/CtaBanner.astro new file mode 100644 index 0000000..07f4eb5 --- /dev/null +++ b/gallery/src/modules/create-theme/templates/base/src/components/cta/CtaBanner.astro @@ -0,0 +1,101 @@ +--- +import Container from '@/components/container/Container.astro'; +--- + +
+ +
+
+

Share your story

+

Build your own gallery with Simple Photo Gallery

+

+ Turn your photos into a fast, beautiful web gallery in minutes and share it with your friends. +

+
+ Create your gallery +
+ +
+ + diff --git a/gallery/src/modules/create-theme/templates/base/src/components/footer/Footer.astro b/gallery/src/modules/create-theme/templates/base/src/components/footer/Footer.astro new file mode 100644 index 0000000..5e00105 --- /dev/null +++ b/gallery/src/modules/create-theme/templates/base/src/components/footer/Footer.astro @@ -0,0 +1,43 @@ +--- +// Footer component for Simple Photo Gallery +--- + + + + diff --git a/gallery/src/modules/create-theme/templates/base/src/components/gallery-section/GallerySection.astro b/gallery/src/modules/create-theme/templates/base/src/components/gallery-section/GallerySection.astro new file mode 100644 index 0000000..0159551 --- /dev/null +++ b/gallery/src/modules/create-theme/templates/base/src/components/gallery-section/GallerySection.astro @@ -0,0 +1,71 @@ +--- +import Container from '@/components/container/Container.astro'; +import GallerySectionHeader from '@/components/gallery-section/GallerySectionHeader.astro'; +import GallerySectionItem from '@/components/gallery-section/GallerySectionItem.astro'; + +import type { ResolvedSection } from '@simple-photo-gallery/common/theme'; + +interface Props { + section: ResolvedSection; + sectionIndex: number; +} + +const { section, sectionIndex } = Astro.props; + +// Filter to only valid images with proper dimensions +const validImages = section.images.filter( + (image) => image.width > 0 && image.height > 0 && (image.thumbnailWidth || 0) > 0 && (image.thumbnailHeight || 0) > 0, +); +--- + +
+ + +
+ {validImages.map((image) => )} +
+ +
+ + diff --git a/gallery/src/modules/create-theme/templates/base/src/components/gallery-section/GallerySectionHeader.astro b/gallery/src/modules/create-theme/templates/base/src/components/gallery-section/GallerySectionHeader.astro new file mode 100644 index 0000000..e5619af --- /dev/null +++ b/gallery/src/modules/create-theme/templates/base/src/components/gallery-section/GallerySectionHeader.astro @@ -0,0 +1,41 @@ +--- +import type { ResolvedSection } from '@simple-photo-gallery/common/theme'; + +interface Props { + section: ResolvedSection; +} + +const { section } = Astro.props; +--- + +
+

{section.title}

+ { + section.parsedDescription && ( +
+ ) + } +
+ + diff --git a/gallery/src/modules/create-theme/templates/base/src/components/gallery-section/GallerySectionItem.astro b/gallery/src/modules/create-theme/templates/base/src/components/gallery-section/GallerySectionItem.astro new file mode 100644 index 0000000..60cabfa --- /dev/null +++ b/gallery/src/modules/create-theme/templates/base/src/components/gallery-section/GallerySectionItem.astro @@ -0,0 +1,97 @@ +--- +import { renderMarkdown } from '@simple-photo-gallery/common/theme'; + +import type { ResolvedImage } from '@simple-photo-gallery/common/theme'; + +interface Props { + image: ResolvedImage; +} + +const { image } = Astro.props; + +// Parse caption as Markdown if it exists +const parsedCaption = image.alt ? await renderMarkdown(image.alt) : ''; +const captionHtml = parsedCaption ? `
${parsedCaption}
` : ''; +--- + + + + + { + image.thumbnailPath && ( + {image.alt} + ) + } + + + diff --git a/gallery/src/modules/create-theme/templates/base/src/components/hero/Hero.astro b/gallery/src/modules/create-theme/templates/base/src/components/hero/Hero.astro new file mode 100644 index 0000000..18fd34a --- /dev/null +++ b/gallery/src/modules/create-theme/templates/base/src/components/hero/Hero.astro @@ -0,0 +1,141 @@ +--- +import HeroScrollToGalleryBtn from '@/components/hero/HeroScrollToGalleryBtn.astro'; + +import type { ResolvedHero } from '@simple-photo-gallery/common/theme'; + +interface Props { + hero: ResolvedHero; +} + +const { hero } = Astro.props; +--- + +
+
+ {hero.headerImageBlurHash && } + + {/* Portrait */} + { + hero.srcsets.portraitAvif && ( + + ) + } + { + hero.srcsets.portraitJpg && ( + + ) + } + + {/* Landscape */} + {hero.srcsets.landscapeAvif && } + {hero.srcsets.landscapeJpg && } + + {/* Fallback */} + + + +
+
+
+

{hero.title}

+ {hero.parsedDescription &&
} + +
+
+ + diff --git a/gallery/src/modules/create-theme/templates/base/src/components/hero/HeroScrollToGalleryBtn.astro b/gallery/src/modules/create-theme/templates/base/src/components/hero/HeroScrollToGalleryBtn.astro new file mode 100644 index 0000000..d275a40 --- /dev/null +++ b/gallery/src/modules/create-theme/templates/base/src/components/hero/HeroScrollToGalleryBtn.astro @@ -0,0 +1,77 @@ +--- + +--- + + + + + + diff --git a/gallery/src/modules/create-theme/templates/base/src/components/lightbox/PhotoSwipe.astro b/gallery/src/modules/create-theme/templates/base/src/components/lightbox/PhotoSwipe.astro new file mode 100644 index 0000000..8b999e5 --- /dev/null +++ b/gallery/src/modules/create-theme/templates/base/src/components/lightbox/PhotoSwipe.astro @@ -0,0 +1,13 @@ + diff --git a/gallery/src/modules/create-theme/templates/base/src/components/sub-galleries/SubGalleries.astro b/gallery/src/modules/create-theme/templates/base/src/components/sub-galleries/SubGalleries.astro new file mode 100644 index 0000000..c2d75bd --- /dev/null +++ b/gallery/src/modules/create-theme/templates/base/src/components/sub-galleries/SubGalleries.astro @@ -0,0 +1,129 @@ +--- +import Container from '@/components/container/Container.astro'; + +import type { ResolvedSubGallery } from '@simple-photo-gallery/common/theme'; + +interface Props { + title?: string; + subGalleries: ResolvedSubGallery[]; +} + +const { title, subGalleries } = Astro.props; +--- + +
+ + { + title && ( +
+

{title}

+
+ ) + } +
+ { + subGalleries.map((subgallery) => ( + +
+ {subgallery.title} +
+
+

{subgallery.title}

+
+ + )) + } +
+ +
+ + diff --git a/gallery/src/modules/create-theme/templates/base/src/layouts/MainHead.astro b/gallery/src/modules/create-theme/templates/base/src/layouts/MainHead.astro index bf186d4..62c34b6 100644 --- a/gallery/src/modules/create-theme/templates/base/src/layouts/MainHead.astro +++ b/gallery/src/modules/create-theme/templates/base/src/layouts/MainHead.astro @@ -1,5 +1,7 @@ --- -import type { GalleryMetadata } from '@simple-photo-gallery/common'; +import { buildHeroSrcset, LANDSCAPE_SIZES, PORTRAIT_SIZES } from '@simple-photo-gallery/common/theme'; + +import type { GalleryMetadata, HeaderImageVariants } from '@simple-photo-gallery/common'; interface Props { title: string; @@ -8,15 +10,77 @@ 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 media attributes in Hero.astro +// Portrait 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'; --- @@ -31,41 +95,76 @@ const thumbnailBasePath = thumbsBaseUrl || 'gallery/images'; {metadata?.keywords && } {metadata?.author && } {metadata?.canonicalUrl || (url && )} + {metadata?.robots && } + {metadata?.language && } - {/* Open Graph */} + {/* Open Graph / Facebook */} {metadata?.image && } + + + {metadata?.ogType && } {metadata?.ogUrl || (url && )} + {metadata?.ogSiteName && } {/* Twitter */} {metadata?.image && } + + + {metadata?.twitterSite && } + {metadata?.twitterCreator && } + + + + + + + { + portraitPreloadSrcset && ( + + ) + } { - headerImageBasename && ( - <> - - - + landscapePreloadSrcset && ( + ) } diff --git a/gallery/src/modules/create-theme/templates/base/src/layouts/MainLayout.astro b/gallery/src/modules/create-theme/templates/base/src/layouts/MainLayout.astro index 1c29558..6da0ba5 100644 --- a/gallery/src/modules/create-theme/templates/base/src/layouts/MainLayout.astro +++ b/gallery/src/modules/create-theme/templates/base/src/layouts/MainLayout.astro @@ -3,7 +3,7 @@ import path from 'node:path'; import MainHead from '@/layouts/MainHead.astro'; -import type { GalleryMetadata } from '@simple-photo-gallery/common'; +import type { GalleryMetadata, HeaderImageVariants } from '@simple-photo-gallery/common'; import type { ThumbnailConfig } from '@simple-photo-gallery/common/theme'; interface Props { @@ -14,10 +14,12 @@ interface Props { metadata?: GalleryMetadata; analyticsScript?: string; headerImage?: string; + headerImageVariants?: HeaderImageVariants; thumbnails?: Required; } -const { title, description, metadata, url, thumbsBaseUrl, analyticsScript, headerImage, thumbnails } = Astro.props; +const { title, description, metadata, url, thumbsBaseUrl, analyticsScript, headerImage, headerImageVariants, thumbnails } = + Astro.props; // Extract basename from headerImage filename const headerImageBasename = headerImage ? path.basename(headerImage, path.extname(headerImage)) : undefined; @@ -32,6 +34,7 @@ const headerImageBasename = headerImage ? path.basename(headerImage, path.extnam url={url} thumbsBaseUrl={thumbsBaseUrl} headerImageBasename={headerImageBasename} + headerImageVariants={headerImageVariants} /> @@ -48,10 +51,101 @@ const headerImageBasename = headerImage ? path.basename(headerImage, path.extnam } body { - font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; + font-family: + 'Montserrat', + -apple-system, + BlinkMacSystemFont, + 'Segoe UI', + Roboto, + sans-serif; line-height: 1.6; color: #333; + font-weight: 400; } - /* TODO: Add your custom styles here */ + body.embed-transparent { + background: transparent; + } + + /* Markdown content styles */ + .markdown-content p { + margin-bottom: 1rem; + } + + .markdown-content p:last-child { + margin-bottom: 0; + } + + .markdown-content strong { + font-weight: 600; + } + + .markdown-content em { + font-style: italic; + } + + .markdown-content a { + color: #374151; + text-decoration: none; + font-weight: 500; + transition: color 0.2s ease; + } + + .markdown-content a:hover { + color: #111827; + } + + /* Light links on dark backgrounds (hero, captions) */ + .hero__description.markdown-content a, + .image-caption.markdown-content a { + color: #d1d5db; + } + + .hero__description.markdown-content a:hover, + .image-caption.markdown-content a:hover { + color: #f3f4f6; + } + + .markdown-content ul, + .markdown-content ol { + margin: 1rem 0; + padding-left: 2rem; + } + + .markdown-content li { + margin-bottom: 0.5rem; + } + + .markdown-content li:last-child { + margin-bottom: 0; + } + + .markdown-content blockquote { + border-left: 3px solid currentColor; + padding-left: 1rem; + margin: 1rem 0; + font-style: italic; + opacity: 0.9; + } + + .markdown-content code { + background-color: rgba(0, 0, 0, 0.1); + padding: 0.2em 0.4em; + border-radius: 3px; + font-family: 'Courier New', Courier, monospace; + font-size: 0.9em; + } + + .markdown-content pre { + background-color: rgba(0, 0, 0, 0.05); + padding: 1rem; + border-radius: 5px; + overflow-x: auto; + margin: 1rem 0; + } + + .markdown-content pre code { + background-color: transparent; + padding: 0; + } diff --git a/gallery/src/modules/create-theme/templates/base/src/pages/index.astro b/gallery/src/modules/create-theme/templates/base/src/pages/index.astro index 95327b7..dca0aa1 100644 --- a/gallery/src/modules/create-theme/templates/base/src/pages/index.astro +++ b/gallery/src/modules/create-theme/templates/base/src/pages/index.astro @@ -3,8 +3,12 @@ import path from 'node:path'; import { loadGalleryData, loadThemeConfig, resolveGalleryData } from '@simple-photo-gallery/common/theme'; -import GalleryItem from '@/components/GalleryItem.astro'; -import Hero from '@/components/Hero.astro'; +import CtaBanner from '@/components/cta/CtaBanner.astro'; +import Footer from '@/components/footer/Footer.astro'; +import GallerySection from '@/components/gallery-section/GallerySection.astro'; +import Hero from '@/components/hero/Hero.astro'; +import PhotoSwipe from '@/components/lightbox/PhotoSwipe.astro'; +import SubGalleries from '@/components/sub-galleries/SubGalleries.astro'; import MainLayout from '@/layouts/MainLayout.astro'; // Load and resolve gallery data - all paths are pre-computed @@ -12,12 +16,27 @@ const galleryJsonPath = import.meta.env.GALLERY_JSON_PATH || './gallery.json'; const raw = loadGalleryData(galleryJsonPath, { validate: true }); // Load theme config from theme root or cwd +// Try current working directory first, then relative to built theme location const themePath = path.resolve(import.meta.dirname, '../..'); const themeConfig = loadThemeConfig(themePath); const gallery = await resolveGalleryData(raw, { galleryJsonPath, themeConfig }); + +const showCtaBanner = gallery.ctaBanner === true; --- + + -
- {/* Render gallery sections */} - { - gallery.sections.map((section) => ( -
- {section.title &&

{section.title}

} - {section.parsedDescription &&
} - -
- {section.images.map((image) => ( - - ))} -
-
- )) - } -
- - - - - +