feat: theming system, documentation, and photo grid regression tests
- Add configurable theme system with 4 presets (studio, minimal, editorial, classic) - Theme controls fonts, colors, accent, photo frames, grain, and header dot - Resolve themes from gallery.yaml: string shorthand or full object override - Inject theme as CSS custom properties on <html> element - Dynamic Google Fonts loading based on theme config - OG image route reads accent/background from theme - Refactor Studio overrides into conditional CSS via data-attributes Documentation: - Add docs/gallery-config.md with comprehensive configuration reference - Add docs/theming.md with preset reference and custom theme guide - Slim README to link to detailed docs Fix CSS regression: - Fix passepartout frame overflow:visible breaking next/image fill rendering - Remove duplicate .photo-grid__item block that stripped overflow:hidden Testing: - Add e2e/photo-grid.spec.ts with 3 regression tests: - Grid items render with real dimensions - overflow:hidden CSS guard (catches the exact bug fixed) - Images load with real pixel data (not blurhash) Tooling: - Add scripts/screenshots.ts for automated theme screenshot generation - Handles dev server lifecycle, theme cycling, FadeIn + lazy image handling
This commit is contained in:
ralksta
4
.gitignore
vendored
4
.gitignore
vendored
@@ -45,3 +45,7 @@ next-env.d.ts
|
||||
|
||||
# internal dev docs
|
||||
dev-docs/
|
||||
|
||||
# generated screenshots
|
||||
docs/screenshots/
|
||||
|
||||
|
||||
64
README.md
64
README.md
@@ -78,63 +78,21 @@ CACHE_TTL=300 # seconds, default: 300
|
||||
RATE_LIMIT_RPM=120 # requests/min/IP, default: 120
|
||||
```
|
||||
|
||||
### Gallery Config (`content/gallery.yaml`)
|
||||
### Gallery Config
|
||||
|
||||
All gallery structure — hero images, albums, subpages, grid layout, footer — is defined in `content/gallery.yaml`.
|
||||
|
||||
→ **[Gallery Configuration Guide](docs/gallery-config.md)**
|
||||
|
||||
### Theming
|
||||
|
||||
Customize the visual identity of your gallery with built-in presets or fine-grained control over colors, fonts, corners, photo frames, and more.
|
||||
|
||||
```yaml
|
||||
# Hero image(s) — single UUID or list for carousel
|
||||
hero: 00000000-0000-0000-0000-000000000000
|
||||
# hero:
|
||||
# - uuid-1
|
||||
# - uuid-2
|
||||
|
||||
# Standalone albums on the homepage
|
||||
albums:
|
||||
- 11111111-1111-1111-1111-111111111111
|
||||
- 22222222-2222-2222-2222-222222222222
|
||||
|
||||
# EXIF on hover (default: true)
|
||||
# exifOnHover: false
|
||||
|
||||
# Global grid layout
|
||||
# grid:
|
||||
# columns: 3
|
||||
# gap: 12
|
||||
# aspectRatio: "1"
|
||||
# layout: masonry # "masonry" or "uniform"
|
||||
|
||||
# Subpages — group albums into collections
|
||||
subpages:
|
||||
- name: Japan
|
||||
grid:
|
||||
columns: 4
|
||||
layout: uniform
|
||||
aspectRatio: '3/2'
|
||||
albums:
|
||||
- uuid-tokyo
|
||||
- uuid-kyoto
|
||||
|
||||
- name: Wedding – Smith
|
||||
password: clientpass123
|
||||
albums:
|
||||
- uuid-wedding
|
||||
theme: minimal # or: studio, editorial, classic
|
||||
```
|
||||
|
||||
See `content/gallery.yaml.example` for the full reference.
|
||||
|
||||
### About Page (`content/about.md`)
|
||||
|
||||
```markdown
|
||||
---
|
||||
portrait: asset-uuid
|
||||
name: Your Name
|
||||
location: City, Country
|
||||
gear:
|
||||
- Camera Body
|
||||
- Favorite Lens
|
||||
---
|
||||
|
||||
Your bio text here.
|
||||
```
|
||||
→ **[Theming Guide](docs/theming.md)**
|
||||
|
||||
## Docker
|
||||
|
||||
|
||||
@@ -1,12 +1,14 @@
|
||||
/**
|
||||
* Dynamic OG image generator — renders social share previews.
|
||||
* Uses next/og (ImageResponse) to create 1200×630 cards.
|
||||
* Reads accent color from theme config.
|
||||
*
|
||||
* GET /api/og?title=Album+Name&subtitle=12+photos
|
||||
*/
|
||||
|
||||
import { ImageResponse } from 'next/og';
|
||||
import { NextRequest } from 'next/server';
|
||||
import { getConfig } from '@/lib/config';
|
||||
|
||||
export const runtime = 'edge';
|
||||
|
||||
@@ -14,6 +16,7 @@ export async function GET(request: NextRequest) {
|
||||
const { searchParams } = request.nextUrl;
|
||||
const title = searchParams.get('title') || 'Gallery';
|
||||
const subtitle = searchParams.get('subtitle') || '';
|
||||
const { theme } = getConfig();
|
||||
|
||||
return new ImageResponse(
|
||||
<div
|
||||
@@ -34,7 +37,7 @@ export async function GET(request: NextRequest) {
|
||||
style={{
|
||||
width: '60px',
|
||||
height: '2px',
|
||||
backgroundColor: '#d4af37',
|
||||
backgroundColor: theme.accent,
|
||||
marginBottom: '40px',
|
||||
}}
|
||||
/>
|
||||
@@ -75,7 +78,7 @@ export async function GET(request: NextRequest) {
|
||||
style={{
|
||||
width: '60px',
|
||||
height: '2px',
|
||||
backgroundColor: '#d4af37',
|
||||
backgroundColor: theme.accent,
|
||||
marginTop: '40px',
|
||||
}}
|
||||
/>
|
||||
|
||||
170
app/globals.css
170
app/globals.css
@@ -279,12 +279,10 @@
|
||||
flex-direction: column;
|
||||
justify-content: flex-end;
|
||||
padding: 24px;
|
||||
background: linear-gradient(
|
||||
to top,
|
||||
rgba(0, 0, 0, 0.8) 0%,
|
||||
rgba(0, 0, 0, 0.3) 40%,
|
||||
transparent 100%
|
||||
);
|
||||
background: linear-gradient(to top,
|
||||
rgba(0, 0, 0, 0.8) 0%,
|
||||
rgba(0, 0, 0, 0.3) 40%,
|
||||
transparent 100%);
|
||||
opacity: 0;
|
||||
transition: opacity var(--transition-normal);
|
||||
}
|
||||
@@ -414,12 +412,10 @@
|
||||
|
||||
/* ── Loading States ───────────────────────────────── */
|
||||
.skeleton {
|
||||
background: linear-gradient(
|
||||
90deg,
|
||||
var(--bg-card) 0%,
|
||||
var(--bg-card-hover) 50%,
|
||||
var(--bg-card) 100%
|
||||
);
|
||||
background: linear-gradient(90deg,
|
||||
var(--bg-card) 0%,
|
||||
var(--bg-card-hover) 50%,
|
||||
var(--bg-card) 100%);
|
||||
background-size: 200% 100%;
|
||||
animation: skeleton-shimmer 1.5s infinite;
|
||||
border-radius: var(--radius-sm);
|
||||
@@ -604,10 +600,11 @@
|
||||
font-weight: 300;
|
||||
}
|
||||
|
||||
/* ── Studio-Inspired Defaults ────────────────────── */
|
||||
/* ── Theme Conditionals ──────────────────────────── */
|
||||
/* Features toggled via data attributes on <html>, set by theme config */
|
||||
|
||||
/* Red dot in header */
|
||||
.header__nav::before {
|
||||
/* ─ Header dot (accent circle in nav) ─ */
|
||||
[data-header-dot='true'] .header__nav::before {
|
||||
content: '';
|
||||
display: block;
|
||||
width: 10px;
|
||||
@@ -618,6 +615,78 @@
|
||||
flex-shrink: 0;
|
||||
}
|
||||
|
||||
/* ─ Passepartout photo frame ─ */
|
||||
[data-photo-frame='passepartout'] .photo-grid__item {
|
||||
border: 1px solid rgba(255, 255, 255, 0.12);
|
||||
padding: 8px 8px 24px;
|
||||
margin-bottom: var(--grid-gap, 24px);
|
||||
background: #111;
|
||||
overflow: hidden;
|
||||
}
|
||||
|
||||
[data-photo-frame='passepartout'][data-theme='light'] .photo-grid__item {
|
||||
border-color: rgba(0, 0, 0, 0.1);
|
||||
background: #fff;
|
||||
}
|
||||
|
||||
[data-photo-frame='passepartout'] .photo-grid__item-exif {
|
||||
position: relative;
|
||||
bottom: auto;
|
||||
left: auto;
|
||||
right: auto;
|
||||
background: none;
|
||||
padding: 8px 0 0;
|
||||
color: var(--text-muted);
|
||||
font-family: var(--font-caption);
|
||||
font-style: italic;
|
||||
font-size: 0.75rem;
|
||||
letter-spacing: 0.02em;
|
||||
white-space: normal;
|
||||
opacity: 1;
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
[data-photo-frame='passepartout'] .photo-grid__item:hover .photo-grid__item-exif {
|
||||
opacity: 1;
|
||||
}
|
||||
|
||||
/* ─ Shadow photo frame ─ */
|
||||
[data-photo-frame='shadow'] .photo-grid__item {
|
||||
border-radius: var(--radius-sm);
|
||||
box-shadow: 0 2px 20px rgba(0, 0, 0, 0.3);
|
||||
overflow: hidden;
|
||||
}
|
||||
|
||||
[data-photo-frame='shadow'][data-theme='light'] .photo-grid__item {
|
||||
box-shadow: 0 2px 16px rgba(0, 0, 0, 0.12);
|
||||
}
|
||||
|
||||
/* ─ Film grain overlay ─ */
|
||||
[data-grain='true'] .photo-grid__item::after {
|
||||
content: '';
|
||||
position: absolute;
|
||||
top: 8px;
|
||||
left: 8px;
|
||||
right: 8px;
|
||||
bottom: 24px;
|
||||
background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.85' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)' opacity='0.04'/%3E%3C/svg%3E");
|
||||
background-size: 128px 128px;
|
||||
pointer-events: none;
|
||||
z-index: 1;
|
||||
mix-blend-mode: overlay;
|
||||
}
|
||||
|
||||
/* Grain without passepartout — fill the whole item */
|
||||
[data-grain='true'][data-photo-frame='none'] .photo-grid__item::after,
|
||||
[data-grain='true'][data-photo-frame='shadow'] .photo-grid__item::after {
|
||||
top: 0;
|
||||
left: 0;
|
||||
right: 0;
|
||||
bottom: 0;
|
||||
}
|
||||
|
||||
/* ── Gallery Aesthetics (all themes) ─────────────── */
|
||||
|
||||
/* Generous spacing — gallery exhibition feel */
|
||||
.main {
|
||||
padding: 64px 40px 120px;
|
||||
@@ -639,68 +708,11 @@
|
||||
letter-spacing: 0.2em;
|
||||
}
|
||||
|
||||
/* Photo grid — passepartout white borders */
|
||||
/* Photo grid gap */
|
||||
.photo-grid {
|
||||
column-gap: var(--grid-gap, 24px);
|
||||
}
|
||||
|
||||
.photo-grid__item {
|
||||
border: 1px solid rgba(255, 255, 255, 0.12);
|
||||
padding: 8px 8px 24px;
|
||||
margin-bottom: var(--grid-gap, 24px);
|
||||
background: #111;
|
||||
border-radius: 0;
|
||||
cursor: pointer;
|
||||
position: relative;
|
||||
overflow: visible;
|
||||
}
|
||||
|
||||
[data-theme='light'] .photo-grid__item {
|
||||
border-color: rgba(0, 0, 0, 0.1);
|
||||
background: #fff;
|
||||
}
|
||||
|
||||
.photo-grid__item img {
|
||||
border-radius: 0;
|
||||
}
|
||||
|
||||
/* Film grain overlay */
|
||||
.photo-grid__item::after {
|
||||
content: '';
|
||||
position: absolute;
|
||||
top: 8px;
|
||||
left: 8px;
|
||||
right: 8px;
|
||||
bottom: 24px;
|
||||
background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.85' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)' opacity='0.04'/%3E%3C/svg%3E");
|
||||
background-size: 128px 128px;
|
||||
pointer-events: none;
|
||||
z-index: 1;
|
||||
mix-blend-mode: overlay;
|
||||
}
|
||||
|
||||
/* Print-style captions (replaces EXIF overlay) */
|
||||
.photo-grid__item-exif {
|
||||
position: relative;
|
||||
bottom: auto;
|
||||
left: auto;
|
||||
right: auto;
|
||||
background: none;
|
||||
padding: 8px 0 0;
|
||||
color: var(--text-muted);
|
||||
font-family: var(--font-caption, 'EB Garamond', Georgia, serif);
|
||||
font-style: italic;
|
||||
font-size: 0.75rem;
|
||||
letter-spacing: 0.02em;
|
||||
white-space: normal;
|
||||
opacity: 1;
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
.photo-grid__item:hover .photo-grid__item-exif {
|
||||
opacity: 1;
|
||||
}
|
||||
|
||||
/* Shutter-click feedback */
|
||||
.photo-grid__item:active img {
|
||||
filter: brightness(0.6);
|
||||
@@ -740,9 +752,9 @@
|
||||
color: var(--accent);
|
||||
}
|
||||
|
||||
/* Album cards — sharper, no rounded corners */
|
||||
/* Album cards */
|
||||
.album-card {
|
||||
border-radius: 0;
|
||||
border-radius: var(--radius-md);
|
||||
border-color: rgba(255, 255, 255, 0.08);
|
||||
}
|
||||
|
||||
@@ -755,7 +767,7 @@
|
||||
transform: none;
|
||||
}
|
||||
|
||||
/* Subpage grid — clean */
|
||||
/* Subpage grid */
|
||||
.subpage-grid__item {
|
||||
border: 1px solid rgba(255, 255, 255, 0.08);
|
||||
}
|
||||
@@ -764,19 +776,17 @@
|
||||
border-color: rgba(0, 0, 0, 0.08);
|
||||
}
|
||||
|
||||
/* Nav link accent on hover */
|
||||
/* Accent hover effects (works with any accent color) */
|
||||
.header__nav-link:hover,
|
||||
.header__nav-link.active {
|
||||
color: var(--accent);
|
||||
border-bottom-color: var(--accent);
|
||||
}
|
||||
|
||||
/* Footer — red accent on hover */
|
||||
.footer__link:hover {
|
||||
color: var(--accent);
|
||||
}
|
||||
|
||||
/* Scroll-to-top — red accent on hover */
|
||||
.scroll-to-top:hover {
|
||||
border-color: var(--accent);
|
||||
color: var(--accent);
|
||||
@@ -846,7 +856,7 @@
|
||||
opacity: 1;
|
||||
}
|
||||
|
||||
.photo-grid__item {
|
||||
[data-photo-frame='passepartout'] .photo-grid__item {
|
||||
padding: 6px 6px 18px;
|
||||
}
|
||||
}
|
||||
@@ -1,6 +1,7 @@
|
||||
/**
|
||||
* Root layout — site header with portfolio-style navigation.
|
||||
* Shows all subpages + standalone albums as nav links.
|
||||
* Injects theme CSS custom properties from gallery.yaml config.
|
||||
*/
|
||||
|
||||
import type { Metadata } from 'next';
|
||||
@@ -10,6 +11,7 @@ import { SubpageNav } from '@/components/SubpageNav';
|
||||
import { ThemeToggle } from '@/components/ThemeToggle';
|
||||
import { ScrollToTop } from '@/components/ScrollToTop';
|
||||
import { Footer } from '@/components/Footer';
|
||||
import { getConfig, getGoogleFontsUrl } from '@/lib/config';
|
||||
|
||||
const siteTitle = process.env.SITE_TITLE || 'Gallery';
|
||||
const siteDescription = 'A curated photography portfolio';
|
||||
@@ -35,8 +37,35 @@ export const metadata: Metadata = {
|
||||
};
|
||||
|
||||
export default function RootLayout({ children }: { children: React.ReactNode }) {
|
||||
const { theme } = getConfig();
|
||||
const fontsUrl = getGoogleFontsUrl(theme);
|
||||
|
||||
// Inject theme values as CSS custom properties
|
||||
const themeVars: Record<string, string> = {
|
||||
'--accent': theme.accent,
|
||||
'--accent-dim': `${theme.accent}1f`,
|
||||
'--font-serif': `'${theme.fonts.heading}', Georgia, 'Times New Roman', serif`,
|
||||
'--font-sans': `'${theme.fonts.body}', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif`,
|
||||
'--font-caption': `'${theme.fonts.caption}', Georgia, serif`,
|
||||
'--radius-sm': `${theme.radius}px`,
|
||||
'--radius-md': `${Math.round(theme.radius * 1.5)}px`,
|
||||
'--radius-lg': `${theme.radius * 2}px`,
|
||||
};
|
||||
|
||||
return (
|
||||
<html lang="en" suppressHydrationWarning>
|
||||
<html
|
||||
lang="en"
|
||||
suppressHydrationWarning
|
||||
style={themeVars as React.CSSProperties}
|
||||
data-grain={theme.grain}
|
||||
data-header-dot={theme.headerDot}
|
||||
data-photo-frame={theme.photoFrame}
|
||||
>
|
||||
<head>
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com" />
|
||||
<link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="anonymous" />
|
||||
<link rel="stylesheet" href={fontsUrl} />
|
||||
</head>
|
||||
<body>
|
||||
<header className="header">
|
||||
<nav className="header__nav">
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
@import url('https://fonts.googleapis.com/css2?family=DM+Sans:wght@300;400;500;600&family=Playfair+Display:wght@400;500;600&family=EB+Garamond:ital,wght@0,400;1,400&display=swap');
|
||||
/* Fonts are loaded dynamically via layout.tsx based on theme config */
|
||||
|
||||
/* ── Design Tokens (Studio Dark — Default) ───────── */
|
||||
/* ── Design Tokens (Fallback Defaults) ───────────── */
|
||||
/* These are overridden at runtime by CSS vars injected from gallery.yaml theme config. */
|
||||
:root {
|
||||
--bg-primary: #1a1a1a;
|
||||
--bg-secondary: #141414;
|
||||
|
||||
@@ -49,3 +49,24 @@ subpages:
|
||||
# instagram: johndoe
|
||||
# email: hello@example.com
|
||||
# website: https://example.com
|
||||
|
||||
# ── Theme ─────────────────────────────────────────────────────
|
||||
# Control the visual identity of your gallery. Use a preset name:
|
||||
# theme: studio # Leica-inspired, red accent, passepartout frames, film grain
|
||||
# theme: minimal # Clean, no distractions, grey accent
|
||||
# theme: editorial # Magazine feel, shadow frames
|
||||
# theme: classic # Warm, golden accent, rounded corners
|
||||
#
|
||||
# Or customize individual properties (defaults from the preset):
|
||||
# theme:
|
||||
# preset: studio # base preset to extend
|
||||
# accent: "#2563eb" # brand/accent color
|
||||
# fonts:
|
||||
# heading: "Inter" # Google Fonts name for headings
|
||||
# body: "Inter" # body text
|
||||
# caption: "JetBrains Mono" # EXIF captions
|
||||
# radius: 8 # border-radius in pixels (0 = sharp)
|
||||
# photoFrame: none # "none" | "passepartout" | "shadow"
|
||||
# grain: false # film grain overlay on photos
|
||||
# headerDot: false # accent dot in the nav bar
|
||||
# heroStyle: split # "split" | "fullbleed" | "minimal"
|
||||
|
||||
113
docs/gallery-config.md
Normal file
113
docs/gallery-config.md
Normal file
@@ -0,0 +1,113 @@
|
||||
# Gallery Configuration
|
||||
|
||||
All gallery structure is defined in `content/gallery.yaml`. Copy the example to get started:
|
||||
|
||||
```bash
|
||||
cp content/gallery.yaml.example content/gallery.yaml
|
||||
```
|
||||
|
||||
## Hero Images
|
||||
|
||||
Single image or crossfade carousel on the homepage:
|
||||
|
||||
```yaml
|
||||
# Single hero image
|
||||
hero: 00000000-0000-0000-0000-000000000000
|
||||
|
||||
# Carousel (crossfade between multiple images)
|
||||
hero:
|
||||
- 00000000-0000-0000-0000-000000000000
|
||||
- 11111111-1111-1111-1111-111111111111
|
||||
- 22222222-2222-2222-2222-222222222222
|
||||
```
|
||||
|
||||
## Standalone Albums
|
||||
|
||||
Albums shown directly on the homepage as cards:
|
||||
|
||||
```yaml
|
||||
albums:
|
||||
- 11111111-1111-1111-1111-111111111111
|
||||
- 22222222-2222-2222-2222-222222222222
|
||||
```
|
||||
|
||||
## Subpages
|
||||
|
||||
Group multiple albums into named collections. URLs are auto-generated from the name:
|
||||
|
||||
```yaml
|
||||
subpages:
|
||||
- name: Japan # → /japan
|
||||
albums:
|
||||
- 33333333-3333-3333-3333-333333333333 # Tokyo
|
||||
- 44444444-4444-4444-4444-444444444444 # Kyoto
|
||||
|
||||
- name: Wedding – Smith # → /wedding-smith
|
||||
password: clientpass123 # password-protected
|
||||
albums:
|
||||
- 55555555-5555-5555-5555-555555555555
|
||||
```
|
||||
|
||||
## Grid Layout
|
||||
|
||||
Configure the photo grid globally or per-subpage:
|
||||
|
||||
```yaml
|
||||
# Global defaults
|
||||
grid:
|
||||
columns: 3 # number of columns (default: 3)
|
||||
gap: 12 # gap in pixels (default: 12)
|
||||
aspectRatio: "1" # "1", "3/2", "auto", etc. (default: "1")
|
||||
layout: masonry # "masonry" or "uniform" (default: "masonry")
|
||||
|
||||
subpages:
|
||||
- name: Japan
|
||||
grid: # per-subpage override
|
||||
columns: 4
|
||||
layout: uniform
|
||||
aspectRatio: "3/2"
|
||||
albums:
|
||||
- ...
|
||||
```
|
||||
|
||||
## EXIF on Hover
|
||||
|
||||
Show camera/lens/settings when hovering over photos (enabled by default):
|
||||
|
||||
```yaml
|
||||
exifOnHover: false # set to false to disable
|
||||
```
|
||||
|
||||
## Footer
|
||||
|
||||
Optional minimal footer with social links:
|
||||
|
||||
```yaml
|
||||
footer:
|
||||
name: John Doe
|
||||
instagram: johndoe
|
||||
email: hello@example.com
|
||||
website: https://example.com
|
||||
```
|
||||
|
||||
## About Page
|
||||
|
||||
Create `content/about.md` with YAML frontmatter:
|
||||
|
||||
```markdown
|
||||
---
|
||||
portrait: asset-uuid-for-your-portrait
|
||||
name: Your Name
|
||||
location: City, Country
|
||||
gear:
|
||||
- Camera Body
|
||||
- Favorite Lens
|
||||
---
|
||||
|
||||
Your bio text here. Supports full Markdown.
|
||||
```
|
||||
|
||||
## Finding UUIDs
|
||||
|
||||
- **Album UUIDs**: In Immich, go to Albums → click an album → the UUID is in the URL bar
|
||||
- **Asset UUIDs**: Click any photo → the UUID is in the URL bar
|
||||
121
docs/theming.md
Normal file
121
docs/theming.md
Normal file
@@ -0,0 +1,121 @@
|
||||
# Theming
|
||||
|
||||
Control the visual identity of your gallery from `content/gallery.yaml`. Choose a built-in preset or customize individual properties — no CSS editing required.
|
||||
|
||||
## Quick Start
|
||||
|
||||
Add a single line to your `gallery.yaml`:
|
||||
|
||||
```yaml
|
||||
theme: minimal
|
||||
```
|
||||
|
||||
That's it. Your entire gallery switches to the minimal theme.
|
||||
|
||||
## Built-in Presets
|
||||
|
||||
| Preset | Look | Accent | Fonts | Corners | Frame | Grain |
|
||||
|--------|------|--------|-------|---------|-------|-------|
|
||||
| **studio** | Leica-inspired, editorial | 🔴 `#e60012` | Playfair Display + DM Sans | Sharp | Passepartout | ✓ |
|
||||
| **minimal** | Clean, no distractions | ⚪ `#666666` | Inter | Sharp | None | ✗ |
|
||||
| **editorial** | Magazine feel | ⚫ `#1a1a1a` | Libre Baskerville + Source Sans | Slight | Shadow | ✗ |
|
||||
| **classic** | Warm, inviting | 🟡 `#8b6914` | Cormorant Garamond + Lato | Rounded | None | ✗ |
|
||||
|
||||
Default is `studio` if no theme is specified.
|
||||
|
||||
## Custom Theme
|
||||
|
||||
Start from any preset and override individual properties:
|
||||
|
||||
```yaml
|
||||
theme:
|
||||
preset: studio # base preset to extend (default: studio)
|
||||
accent: "#2563eb" # brand/accent color (any hex)
|
||||
fonts:
|
||||
heading: "Inter" # Google Fonts name for headings
|
||||
body: "Inter" # body text
|
||||
caption: "JetBrains Mono" # EXIF captions
|
||||
radius: 8 # border-radius in px (0 = sharp corners)
|
||||
photoFrame: none # "none" | "passepartout" | "shadow"
|
||||
grain: false # film grain overlay on photos
|
||||
headerDot: false # accent-colored dot in the nav bar
|
||||
heroStyle: split # "split" | "fullbleed" | "minimal"
|
||||
```
|
||||
|
||||
All properties are optional — omitted values fall back to the preset defaults.
|
||||
|
||||
## Properties Reference
|
||||
|
||||
### `accent`
|
||||
|
||||
The brand color used for hover effects, navigation highlights, the header dot, and OG social preview images.
|
||||
|
||||
### `fonts`
|
||||
|
||||
Google Fonts names. Fonts are loaded automatically — just use the name as it appears on [fonts.google.com](https://fonts.google.com). Three font slots:
|
||||
|
||||
- **heading** — album titles, hero title, section labels
|
||||
- **body** — navigation, descriptions, UI text
|
||||
- **caption** — EXIF metadata, photo captions
|
||||
|
||||
### `radius`
|
||||
|
||||
Border radius in pixels applied to photo grid items and album cards:
|
||||
- `0` — sharp, editorial corners
|
||||
- `4-8` — subtle rounding
|
||||
- `12+` — soft, modern feel
|
||||
|
||||
### `photoFrame`
|
||||
|
||||
How photos are framed in the grid:
|
||||
|
||||
- **`none`** — photos fill the grid cell directly
|
||||
- **`passepartout`** — museum-style mat border around each photo with print-style EXIF captions below
|
||||
- **`shadow`** — subtle drop shadow behind each photo
|
||||
|
||||
### `grain`
|
||||
|
||||
When `true`, a subtle film grain texture overlays each photo in the grid. Adds an analog, filmic character.
|
||||
|
||||
### `headerDot`
|
||||
|
||||
When `true`, shows a small accent-colored dot in the navigation bar (inspired by the Leica red dot).
|
||||
|
||||
### `heroStyle`
|
||||
|
||||
Controls the homepage hero layout:
|
||||
- **`split`** — title/nav on the left, hero image on the right (default)
|
||||
- **`fullbleed`** — hero image fills the entire viewport
|
||||
- **`minimal`** — text-only, no hero image
|
||||
|
||||
## Examples
|
||||
|
||||
### Minimal portfolio
|
||||
```yaml
|
||||
theme:
|
||||
preset: minimal
|
||||
accent: "#0066cc"
|
||||
fonts:
|
||||
heading: "Outfit"
|
||||
body: "Outfit"
|
||||
```
|
||||
|
||||
### Film photography blog
|
||||
```yaml
|
||||
theme:
|
||||
preset: studio
|
||||
accent: "#d4a017"
|
||||
grain: true
|
||||
photoFrame: passepartout
|
||||
```
|
||||
|
||||
### Modern magazine
|
||||
```yaml
|
||||
theme:
|
||||
preset: editorial
|
||||
radius: 12
|
||||
fonts:
|
||||
heading: "Fraunces"
|
||||
body: "Inter"
|
||||
caption: "IBM Plex Mono"
|
||||
```
|
||||
75
e2e/photo-grid.spec.ts
Normal file
75
e2e/photo-grid.spec.ts
Normal file
@@ -0,0 +1,75 @@
|
||||
import { test, expect } from '@playwright/test';
|
||||
|
||||
test.describe('Photo Grid', () => {
|
||||
// Use a known public subpage that has photos
|
||||
const GRID_URL = '/deutschland/kloster-chorin-2024';
|
||||
|
||||
test('renders grid items with visible images', async ({ page }) => {
|
||||
await page.goto(GRID_URL);
|
||||
|
||||
// Grid container should exist
|
||||
const grid = page.locator('.photo-grid');
|
||||
await expect(grid).toBeVisible();
|
||||
|
||||
// Should have grid items
|
||||
const items = grid.locator('.photo-grid__item');
|
||||
const count = await items.count();
|
||||
expect(count).toBeGreaterThan(0);
|
||||
|
||||
// Scroll to trigger IntersectionObserver (FadeIn)
|
||||
await items.first().scrollIntoViewIfNeeded();
|
||||
await page.waitForTimeout(1000);
|
||||
|
||||
// First grid item should have real dimensions (not collapsed)
|
||||
const firstItem = items.first();
|
||||
const box = await firstItem.boundingBox();
|
||||
expect(box).not.toBeNull();
|
||||
expect(box!.width).toBeGreaterThan(100);
|
||||
expect(box!.height).toBeGreaterThan(50);
|
||||
|
||||
// Image inside should exist and have the fill layout
|
||||
const img = firstItem.locator('img');
|
||||
await expect(img).toBeAttached();
|
||||
});
|
||||
|
||||
test('grid items have overflow hidden (CSS regression)', async ({ page }) => {
|
||||
// This test guards against the CSS cascade bug where a later rule
|
||||
// strips `overflow: hidden` from .photo-grid__item, which breaks
|
||||
// next/image fill rendering.
|
||||
await page.goto(GRID_URL);
|
||||
|
||||
const grid = page.locator('.photo-grid');
|
||||
await expect(grid).toBeVisible();
|
||||
|
||||
const item = grid.locator('.photo-grid__item').first();
|
||||
await item.scrollIntoViewIfNeeded();
|
||||
|
||||
const overflow = await item.evaluate((el) => getComputedStyle(el).overflow);
|
||||
expect(overflow).toBe('hidden');
|
||||
});
|
||||
|
||||
test('images load with real content (not just blurhash)', async ({ page }) => {
|
||||
await page.goto(GRID_URL);
|
||||
|
||||
// Scroll to trigger lazy loading
|
||||
const grid = page.locator('.photo-grid');
|
||||
await grid.scrollIntoViewIfNeeded();
|
||||
await page.waitForTimeout(3000);
|
||||
|
||||
// Check that at least one image has loaded with real pixel data
|
||||
const imgLoaded = await page.evaluate(() => {
|
||||
const img = document.querySelector('.photo-grid__item img') as HTMLImageElement;
|
||||
if (!img) return { found: false };
|
||||
return {
|
||||
found: true,
|
||||
complete: img.complete,
|
||||
naturalWidth: img.naturalWidth,
|
||||
src: img.src.substring(0, 60),
|
||||
};
|
||||
});
|
||||
|
||||
expect(imgLoaded.found).toBe(true);
|
||||
expect(imgLoaded.complete).toBe(true);
|
||||
expect(imgLoaded.naturalWidth).toBeGreaterThan(0);
|
||||
});
|
||||
});
|
||||
135
lib/config.ts
135
lib/config.ts
@@ -31,11 +31,80 @@ export interface FooterConfig {
|
||||
website?: string;
|
||||
}
|
||||
|
||||
/** Theme configuration — controls the visual identity of the gallery. */
|
||||
export interface ThemeConfig {
|
||||
preset: string;
|
||||
accent: string;
|
||||
fonts: { heading: string; body: string; caption: string };
|
||||
radius: number;
|
||||
photoFrame: 'none' | 'passepartout' | 'shadow';
|
||||
grain: boolean;
|
||||
headerDot: boolean;
|
||||
heroStyle: 'split' | 'fullbleed' | 'minimal';
|
||||
}
|
||||
|
||||
// ── Theme Presets ──────────────────────────────────────────────
|
||||
|
||||
const THEME_PRESETS: Record<string, ThemeConfig> = {
|
||||
studio: {
|
||||
preset: 'studio',
|
||||
accent: '#e60012',
|
||||
fonts: { heading: 'Playfair Display', body: 'DM Sans', caption: 'EB Garamond' },
|
||||
radius: 0,
|
||||
photoFrame: 'passepartout',
|
||||
grain: true,
|
||||
headerDot: true,
|
||||
heroStyle: 'split',
|
||||
},
|
||||
minimal: {
|
||||
preset: 'minimal',
|
||||
accent: '#666666',
|
||||
fonts: { heading: 'Inter', body: 'Inter', caption: 'JetBrains Mono' },
|
||||
radius: 0,
|
||||
photoFrame: 'none',
|
||||
grain: false,
|
||||
headerDot: false,
|
||||
heroStyle: 'split',
|
||||
},
|
||||
editorial: {
|
||||
preset: 'editorial',
|
||||
accent: '#1a1a1a',
|
||||
fonts: { heading: 'Libre Baskerville', body: 'Source Sans 3', caption: 'Source Sans 3' },
|
||||
radius: 4,
|
||||
photoFrame: 'shadow',
|
||||
grain: false,
|
||||
headerDot: false,
|
||||
heroStyle: 'split',
|
||||
},
|
||||
classic: {
|
||||
preset: 'classic',
|
||||
accent: '#8b6914',
|
||||
fonts: { heading: 'Cormorant Garamond', body: 'Lato', caption: 'Lato' },
|
||||
radius: 8,
|
||||
photoFrame: 'none',
|
||||
grain: false,
|
||||
headerDot: false,
|
||||
heroStyle: 'split',
|
||||
},
|
||||
};
|
||||
|
||||
/** Raw YAML structure (before validation). */
|
||||
interface GalleryYaml {
|
||||
hero?: string | string[];
|
||||
albums?: string[];
|
||||
exifOnHover?: boolean;
|
||||
theme?:
|
||||
| string
|
||||
| {
|
||||
preset?: string;
|
||||
accent?: string;
|
||||
fonts?: { heading?: string; body?: string; caption?: string };
|
||||
radius?: number;
|
||||
photoFrame?: string;
|
||||
grain?: boolean;
|
||||
headerDot?: boolean;
|
||||
heroStyle?: string;
|
||||
};
|
||||
grid?: {
|
||||
columns?: number;
|
||||
gap?: number;
|
||||
@@ -133,12 +202,74 @@ export interface AppConfig {
|
||||
exifOnHover: boolean;
|
||||
/** Photo grid layout configuration. */
|
||||
grid: GridConfig;
|
||||
/** Theme configuration. */
|
||||
theme: ThemeConfig;
|
||||
/** Footer social links config. */
|
||||
footer: FooterConfig | null;
|
||||
cacheTtl: number;
|
||||
rateLimitRpm: number;
|
||||
}
|
||||
|
||||
// ── Theme resolution ───────────────────────────────────────────
|
||||
|
||||
const VALID_PHOTO_FRAMES = ['none', 'passepartout', 'shadow'];
|
||||
const VALID_HERO_STYLES = ['split', 'fullbleed', 'minimal'];
|
||||
|
||||
function resolveTheme(raw?: GalleryYaml['theme']): ThemeConfig {
|
||||
// No theme key → default preset
|
||||
if (!raw) return { ...THEME_PRESETS.studio };
|
||||
|
||||
// String shorthand: `theme: minimal`
|
||||
if (typeof raw === 'string') {
|
||||
const preset = THEME_PRESETS[raw];
|
||||
if (!preset) {
|
||||
throw new Error(
|
||||
`Unknown theme preset "${raw}". Valid presets: ${Object.keys(THEME_PRESETS).join(', ')}`,
|
||||
);
|
||||
}
|
||||
return { ...preset };
|
||||
}
|
||||
|
||||
// Object: merge with base preset
|
||||
const baseName = raw.preset ?? 'studio';
|
||||
const base = THEME_PRESETS[baseName];
|
||||
if (!base) {
|
||||
throw new Error(
|
||||
`Unknown theme preset "${baseName}". Valid presets: ${Object.keys(THEME_PRESETS).join(', ')}`,
|
||||
);
|
||||
}
|
||||
|
||||
return {
|
||||
preset: baseName,
|
||||
accent: raw.accent ?? base.accent,
|
||||
fonts: {
|
||||
heading: raw.fonts?.heading ?? base.fonts.heading,
|
||||
body: raw.fonts?.body ?? base.fonts.body,
|
||||
caption: raw.fonts?.caption ?? base.fonts.caption,
|
||||
},
|
||||
radius: raw.radius ?? base.radius,
|
||||
photoFrame: VALID_PHOTO_FRAMES.includes(raw.photoFrame ?? '')
|
||||
? (raw.photoFrame as ThemeConfig['photoFrame'])
|
||||
: base.photoFrame,
|
||||
grain: raw.grain ?? base.grain,
|
||||
headerDot: raw.headerDot ?? base.headerDot,
|
||||
heroStyle: VALID_HERO_STYLES.includes(raw.heroStyle ?? '')
|
||||
? (raw.heroStyle as ThemeConfig['heroStyle'])
|
||||
: base.heroStyle,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Build a Google Fonts URL for the theme's fonts.
|
||||
* Deduplicates fonts and includes key weights.
|
||||
*/
|
||||
export function getGoogleFontsUrl(theme: ThemeConfig): string {
|
||||
const weights = '300;400;500;600';
|
||||
const families = [...new Set([theme.fonts.heading, theme.fonts.body, theme.fonts.caption])];
|
||||
const params = families.map((f) => `family=${f.replace(/ /g, '+')}:wght@${weights}`).join('&');
|
||||
return `https://fonts.googleapis.com/css2?${params}&display=swap`;
|
||||
}
|
||||
|
||||
// ── Config builder ─────────────────────────────────────────────
|
||||
|
||||
let _config: AppConfig | null = null;
|
||||
@@ -150,6 +281,9 @@ export function getConfig(): AppConfig {
|
||||
const apiKey = env.IMMICH_API_KEY;
|
||||
const gallery = loadGalleryYaml();
|
||||
|
||||
// Resolve theme: string shorthand → preset, object → merged with preset base
|
||||
const theme = resolveTheme(gallery.theme);
|
||||
|
||||
// Parse standalone albums
|
||||
const standaloneAlbumIds = (gallery.albums ?? []).map((id) =>
|
||||
validateUuid(id, 'gallery.yaml albums'),
|
||||
@@ -216,6 +350,7 @@ export function getConfig(): AppConfig {
|
||||
aspectRatio: gallery.grid?.aspectRatio ?? '1',
|
||||
layout: (gallery.grid?.layout === 'uniform' ? 'uniform' : 'masonry') as GridConfig['layout'],
|
||||
},
|
||||
theme,
|
||||
footer: gallery.footer
|
||||
? {
|
||||
name: gallery.footer.name,
|
||||
|
||||
200
scripts/screenshots.ts
Normal file
200
scripts/screenshots.ts
Normal file
@@ -0,0 +1,200 @@
|
||||
/**
|
||||
* Theme Screenshot Generator
|
||||
*
|
||||
* Captures homepage and grid view screenshots for each theme preset.
|
||||
* Uses Playwright to wait for images to fully load (not just blurhash placeholders).
|
||||
*
|
||||
* Usage:
|
||||
* npx tsx scripts/screenshots.ts
|
||||
*
|
||||
* Prerequisites:
|
||||
* - Dev server NOT running (script manages its own server lifecycle)
|
||||
* - Playwright browsers installed: npx playwright install chromium
|
||||
*
|
||||
* Output:
|
||||
* docs/screenshots/theme-{preset}-{page}.png
|
||||
*/
|
||||
|
||||
import { execSync, spawn, type ChildProcess } from 'child_process';
|
||||
import fs from 'fs';
|
||||
import path from 'path';
|
||||
|
||||
const THEMES = ['studio', 'minimal', 'editorial', 'classic'];
|
||||
const BASE_URL = 'http://localhost:3000';
|
||||
const GRID_PATH = '/deutschland/kloster-chorin-2024'; // public subpage with photos
|
||||
const OUTPUT_DIR = path.join(process.cwd(), 'docs', 'screenshots');
|
||||
const GALLERY_YAML = path.join(process.cwd(), 'content', 'gallery.yaml');
|
||||
const VIEWPORT = { width: 1440, height: 900 };
|
||||
const IMAGE_LOAD_TIMEOUT = 8000; // ms to wait for images after networkidle
|
||||
|
||||
async function main() {
|
||||
// Ensure output directory exists
|
||||
fs.mkdirSync(OUTPUT_DIR, { recursive: true });
|
||||
|
||||
// Read original gallery.yaml to restore later
|
||||
const originalYaml = fs.readFileSync(GALLERY_YAML, 'utf8');
|
||||
|
||||
// Dynamic import for Playwright (may not be installed globally)
|
||||
const { chromium } = await import('playwright');
|
||||
const browser = await chromium.launch();
|
||||
|
||||
try {
|
||||
for (const theme of THEMES) {
|
||||
console.log(`\n🎨 Theme: ${theme}`);
|
||||
console.log('─'.repeat(50));
|
||||
|
||||
// Update gallery.yaml with the theme
|
||||
const yamlWithTheme = setThemeInYaml(originalYaml, theme);
|
||||
fs.writeFileSync(GALLERY_YAML, yamlWithTheme);
|
||||
|
||||
// Start dev server
|
||||
console.log(' ⏳ Starting dev server...');
|
||||
const server = startDevServer();
|
||||
await waitForServer(BASE_URL, 15000);
|
||||
console.log(' ✅ Server ready');
|
||||
|
||||
const context = await browser.newContext({ viewport: VIEWPORT });
|
||||
const page = await context.newPage();
|
||||
|
||||
// ── Homepage screenshot ──
|
||||
console.log(' 📸 Capturing homepage...');
|
||||
await page.goto(BASE_URL, { waitUntil: 'networkidle' });
|
||||
await waitForImages(page);
|
||||
await page.screenshot({
|
||||
path: path.join(OUTPUT_DIR, `theme-${theme}-home.png`),
|
||||
fullPage: false,
|
||||
});
|
||||
console.log(` ✅ theme-${theme}-home.png`);
|
||||
|
||||
// ── Grid view screenshot ──
|
||||
console.log(' 📸 Capturing grid view...');
|
||||
await page.goto(`${BASE_URL}${GRID_PATH}`, { waitUntil: 'networkidle' });
|
||||
// Force all fade-in elements visible (don't scroll — keep album title in view)
|
||||
await page.evaluate(() => {
|
||||
document.querySelectorAll('.fade-in').forEach(el => el.classList.add('fade-in--visible'));
|
||||
// Trigger lazy images by switching to eager loading
|
||||
document.querySelectorAll('img[loading="lazy"]').forEach(img => {
|
||||
(img as HTMLImageElement).loading = 'eager';
|
||||
});
|
||||
});
|
||||
await waitForImages(page);
|
||||
// Extra settle time for late-loading images in lower columns
|
||||
await page.waitForTimeout(3000);
|
||||
await page.screenshot({
|
||||
path: path.join(OUTPUT_DIR, `theme-${theme}-grid.png`),
|
||||
fullPage: false,
|
||||
});
|
||||
console.log(` ✅ theme-${theme}-grid.png`);
|
||||
|
||||
await context.close();
|
||||
|
||||
// Stop dev server
|
||||
server.kill('SIGTERM');
|
||||
await new Promise((resolve) => server.on('close', resolve));
|
||||
console.log(' 🛑 Server stopped');
|
||||
}
|
||||
} finally {
|
||||
// Always restore original gallery.yaml
|
||||
fs.writeFileSync(GALLERY_YAML, originalYaml);
|
||||
console.log('\n✅ Restored original gallery.yaml');
|
||||
await browser.close();
|
||||
}
|
||||
|
||||
console.log(`\n🎉 Done! Screenshots saved to ${OUTPUT_DIR}/`);
|
||||
console.log(` ${fs.readdirSync(OUTPUT_DIR).filter(f => f.endsWith('.png')).join(', ')}`);
|
||||
}
|
||||
|
||||
// ── Helpers ──────────────────────────────────────────────────────
|
||||
|
||||
function setThemeInYaml(yaml: string, theme: string): string {
|
||||
// Replace existing theme line or insert after the header comment
|
||||
if (/^theme:\s*.+$/m.test(yaml)) {
|
||||
return yaml.replace(/^theme:\s*.+$/m, `theme: ${theme}`);
|
||||
}
|
||||
// Insert theme after the header comments
|
||||
const marker = '# Secrets (API key, server URL) stay in .env.local.';
|
||||
return yaml.replace(marker, `${marker}\n\ntheme: ${theme}`);
|
||||
}
|
||||
|
||||
function startDevServer(): ChildProcess {
|
||||
const server = spawn('npm', ['run', 'dev'], {
|
||||
cwd: process.cwd(),
|
||||
stdio: 'pipe',
|
||||
env: { ...process.env },
|
||||
});
|
||||
|
||||
// Suppress server output unless DEBUG is set
|
||||
if (process.env.DEBUG) {
|
||||
server.stdout?.pipe(process.stdout);
|
||||
server.stderr?.pipe(process.stderr);
|
||||
}
|
||||
|
||||
return server;
|
||||
}
|
||||
|
||||
async function waitForServer(url: string, timeoutMs: number): Promise<void> {
|
||||
const start = Date.now();
|
||||
while (Date.now() - start < timeoutMs) {
|
||||
try {
|
||||
const res = await fetch(url);
|
||||
if (res.ok) return;
|
||||
} catch {
|
||||
// Server not ready yet
|
||||
}
|
||||
await sleep(500);
|
||||
}
|
||||
throw new Error(`Server did not start within ${timeoutMs}ms`);
|
||||
}
|
||||
|
||||
/**
|
||||
* Wait for all <img> elements to finish loading their full-resolution images.
|
||||
* This prevents capturing blurhash placeholders instead of real photos.
|
||||
*/
|
||||
async function waitForImages(page: import('playwright').Page): Promise<void> {
|
||||
await page.waitForTimeout(1000); // Initial settle
|
||||
|
||||
await page.evaluate((timeout) => {
|
||||
return new Promise<void>((resolve) => {
|
||||
const images = Array.from(document.querySelectorAll('img'));
|
||||
let pending = images.filter((img) => !img.complete).length;
|
||||
|
||||
if (pending === 0) {
|
||||
// All images already loaded, wait a bit for any CSS transitions
|
||||
setTimeout(resolve, 500);
|
||||
return;
|
||||
}
|
||||
|
||||
const done = () => {
|
||||
pending--;
|
||||
if (pending <= 0) setTimeout(resolve, 500);
|
||||
};
|
||||
|
||||
images.forEach((img) => {
|
||||
if (!img.complete) {
|
||||
img.addEventListener('load', done);
|
||||
img.addEventListener('error', done);
|
||||
}
|
||||
});
|
||||
|
||||
// Safety timeout
|
||||
setTimeout(resolve, timeout);
|
||||
});
|
||||
}, IMAGE_LOAD_TIMEOUT);
|
||||
}
|
||||
|
||||
function sleep(ms: number): Promise<void> {
|
||||
return new Promise((resolve) => setTimeout(resolve, ms));
|
||||
}
|
||||
|
||||
// ── Run ──────────────────────────────────────────────────────────
|
||||
main().catch((err) => {
|
||||
console.error('❌ Screenshot generation failed:', err);
|
||||
// Try to restore gallery.yaml on error
|
||||
try {
|
||||
const original = fs.readFileSync(GALLERY_YAML + '.bak', 'utf8');
|
||||
fs.writeFileSync(GALLERY_YAML, original);
|
||||
} catch {
|
||||
// Backup may not exist
|
||||
}
|
||||
process.exit(1);
|
||||
});
|
||||
Reference in New Issue
Block a user