Koko210/immich-folio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add smart map view with location-level clustering

Browse Source 
- /map page with Leaflet (CartoDB dark tiles)
- Photos clustered by city/country (not per-photo)
- /api/map endpoint with encrypted cover asset IDs
- Configurable via gallery.yaml (map: true/false)
- Conditional nav link in header
- CSP updated for Leaflet CDN and tile servers
- Theme-aware popups with cover thumbnails and album links
This commit is contained in:
ralksta
2026-02-15 23:07:04 +01:00
parent 424f7558c6
commit 62a7b178d6
13 changed files with 555 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
app/api/map/route.ts Normal file
View File

@@ -0,0 +1,42 @@
/**
* Map data API — returns location-level markers for the map view.
* Each marker represents a unique city/country with averaged GPS coords.
* Cover asset IDs are encrypted for security.
*/
import { NextResponse } from 'next/server';
import { immich } from '@/lib/immich';
import { getConfig } from '@/lib/config';
import { imageUrl } from '@/lib/urls';
export const dynamic = 'force-dynamic';
export async function GET() {
const config = getConfig();
if (!config.map) {
return NextResponse.json({ error: 'Map is not enabled' }, { status: 404 });
}
const locations = await immich.getMapData();
// Encrypt cover asset IDs and convert to public-safe image URLs
const publicLocations = locations.map((loc) => ({
city: loc.city,
country: loc.country,
lat: loc.lat,
lng: loc.lng,
photoCount: loc.photoCount,
coverUrl: imageUrl(loc.coverAssetId, 'thumbnail'),
albums: loc.albums.map((a) => ({
name: a.name,
url: a.subpageSlug ? `/${a.subpageSlug}/${a.slug}` : `/${a.slug}`,
})),
}));
return NextResponse.json(publicLocations, {
headers: {
'Cache-Control': `public, max-age=${Math.floor(config.cacheTtl / 1000)}, stale-while-revalidate=60`,
},
});
}

8
app/layout.tsx
View File

@@ -38,7 +38,8 @@ export const metadata: Metadata = {
};
export default function RootLayout({ children }: { children: React.ReactNode }) {
const { theme } = getConfig();
const config = getConfig();
const { theme } = config;
const fontsUrl = getGoogleFontsUrl(theme);
// Inject theme values as CSS custom properties
@@ -78,6 +79,11 @@ export default function RootLayout({ children }: { children: React.ReactNode })
<Link href="/about" className="header__nav-link">
About
</Link>
{config.map && (
<Link href="/map" className="header__nav-link">
Map
</Link>
)}
<ThemeToggle />
</nav>
</header>

174
app/map/map.css Normal file
View File

@@ -0,0 +1,174 @@
/* ── Map Page ──────────────────────────────────────────────── */
.map-page {
display: flex;
flex-direction: column;
min-height: calc(100vh - var(--header-height, 64px));
}
.map-page__header {
padding: 2rem var(--page-padding, 2rem) 1rem;
}
.map-page__title {
font-family: var(--font-heading);
font-size: clamp(1.5rem, 4vw, 2.5rem);
font-weight: 600;
margin: 0.5rem 0 0.25rem;
color: var(--text-primary);
}
.map-page__subtitle {
font-family: var(--font-body);
font-size: 0.875rem;
color: var(--text-secondary);
margin: 0;
}
/* ── Map Container ─────────────────────────────────────────── */
.map-container {
flex: 1;
min-height: 500px;
margin: 0 var(--page-padding, 2rem) 2rem;
border-radius: var(--radius, 0);
overflow: hidden;
border: 1px solid var(--border-color, rgba(128, 128, 128, 0.15));
}
.map-container__loading {
display: flex;
align-items: center;
justify-content: center;
height: 500px;
color: var(--text-secondary);
font-family: var(--font-body);
font-size: 0.875rem;
}
/* ── Map Popups ────────────────────────────────────────────── */
.leaflet-popup-content-wrapper {
background: var(--bg-primary, #1a1a1a) !important;
color: var(--text-primary, #fff) !important;
border-radius: var(--radius, 4px) !important;
box-shadow: 0 8px 32px rgba(0, 0, 0, 0.4) !important;
border: 1px solid var(--border-color, rgba(128, 128, 128, 0.15)) !important;
padding: 0 !important;
overflow: hidden;
}
.leaflet-popup-tip {
background: var(--bg-primary, #1a1a1a) !important;
border: 1px solid var(--border-color, rgba(128, 128, 128, 0.15)) !important;
border-top: none !important;
border-left: none !important;
}
.leaflet-popup-content {
margin: 0 !important;
min-width: 200px;
}
.map-popup {
font-family: var(--font-body);
}
.map-popup__cover {
width: 100%;
height: 120px;
object-fit: cover;
display: block;
}
.map-popup__body {
padding: 0.75rem 1rem;
}
.map-popup__city {
font-family: var(--font-heading);
font-size: 0.9375rem;
font-weight: 600;
margin: 0 0 0.125rem;
color: var(--text-primary);
}
.map-popup__country {
font-family: var(--font-caption);
font-size: 0.6875rem;
text-transform: uppercase;
letter-spacing: 0.08em;
color: var(--text-secondary);
margin: 0 0 0.5rem;
}
.map-popup__count {
font-family: var(--font-caption);
font-size: 0.75rem;
color: var(--text-secondary);
margin-bottom: 0.5rem;
}
.map-popup__albums {
display: flex;
flex-direction: column;
gap: 0.25rem;
}
.map-popup__album-link {
font-size: 0.8125rem;
color: var(--accent, #e60012);
text-decoration: none;
transition: opacity 0.15s;
}
.map-popup__album-link:hover {
opacity: 0.7;
}
/* ── Custom Marker ─────────────────────────────────────────── */
.map-marker {
display: flex;
align-items: center;
justify-content: center;
width: 32px;
height: 32px;
border-radius: 50%;
background: var(--accent, #e60012);
color: #fff;
font-family: var(--font-caption);
font-size: 0.6875rem;
font-weight: 700;
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.3);
border: 2px solid rgba(255, 255, 255, 0.9);
cursor: pointer;
transition: transform 0.15s ease;
}
.map-marker:hover {
transform: scale(1.15);
}
/* ── Leaflet overrides ─────────────────────────────────────── */
.leaflet-control-attribution {
background: var(--bg-primary, #1a1a1a) !important;
color: var(--text-secondary, #888) !important;
font-size: 0.625rem !important;
opacity: 0.7;
}
.leaflet-control-attribution a {
color: var(--text-secondary, #888) !important;
}
.leaflet-control-zoom a {
background: var(--bg-primary, #1a1a1a) !important;
color: var(--text-primary, #fff) !important;
border-color: var(--border-color, rgba(128, 128, 128, 0.15)) !important;
}
.leaflet-control-zoom a:hover {
background: var(--bg-secondary, #222) !important;
}

46
app/map/page.tsx Normal file
View File

@@ -0,0 +1,46 @@
/**
* Map page — server component shell for the interactive map.
* Loads Leaflet CSS, renders the MapView client component.
*/
import { getConfig } from '@/lib/config';
import { notFound } from 'next/navigation';
import { MapView } from '@/components/MapView';
import { BackLink } from '@/components/BackLink';
import type { Metadata } from 'next';
import './map.css';
export const dynamic = 'force-dynamic';
export const metadata: Metadata = {
title: 'Map',
};
export default function MapPage() {
const config = getConfig();
if (!config.map) {
notFound();
}
return (
<>
{/* Leaflet CSS from CDN */}
{/* eslint-disable-next-line @next/next/no-page-custom-font */}
<link
rel="stylesheet"
href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css"
integrity="sha256-p4NxAoJBhIIN+hmNHrzRCf9tD/miZyoHS5obTRR9BMY="
crossOrigin=""
/>
<div className="map-page">
<div className="map-page__header">
<BackLink href="/" label="Back to Gallery" />
<h1 className="map-page__title">Map</h1>
<p className="map-page__subtitle">Where the photos were taken</p>
</div>
<MapView />
</div>
</>
);
}

150
components/MapView.tsx Normal file
View File

@@ -0,0 +1,150 @@
'use client';
/**
* MapView — client component that initializes Leaflet, fetches /api/map,
* and renders location-level markers with themed popups.
*/
import { useEffect, useRef, useState } from 'react';
interface MapLocationPublic {
city: string;
country: string;
lat: number;
lng: number;
photoCount: number;
coverUrl: string;
albums: { name: string; url: string }[];
}
export function MapView() {
const containerRef = useRef<HTMLDivElement>(null);
const mapRef = useRef<unknown>(null);
const [loading, setLoading] = useState(true);
const [error, setError] = useState<string | null>(null);
useEffect(() => {
let cancelled = false;
async function init() {
// Dynamically import Leaflet (client-only)
const L = (await import('leaflet')).default;
if (cancelled || !containerRef.current || mapRef.current) return;
// Fetch map data
const res = await fetch('/api/map');
if (!res.ok) {
setError('Failed to load map data');
setLoading(false);
return;
}
const locations: MapLocationPublic[] = await res.json();
if (cancelled) return;
// Initialize map
const map = L.map(containerRef.current, {
zoomControl: true,
attributionControl: true,
});
mapRef.current = map;
// Dark-themed tiles (CartoDB Dark Matter)
L.tileLayer('https://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}{r}.png', {
attribution: '&copy; <a href="https://www.openstreetmap.org/copyright">OSM</a> &copy; <a href="https://carto.com/">CARTO</a>',
subdomains: 'abcd',
maxZoom: 19,
}).addTo(map);
if (locations.length === 0) {
// No geotagged photos — show world view
map.setView([20, 0], 2);
setLoading(false);
return;
}
// Create markers with custom HTML icons
const markers: L.Marker[] = [];
for (const loc of locations) {
const icon = L.divIcon({
className: '',
html: `<div class="map-marker">${loc.photoCount}</div>`,
iconSize: [32, 32],
iconAnchor: [16, 16],
popupAnchor: [0, -20],
});
const albumLinks = loc.albums
.map((a) => `<a href="${a.url}" class="map-popup__album-link">${a.name} →</a>`)
.join('');
const popupHtml = `
<div class="map-popup">
<img src="${loc.coverUrl}" alt="${loc.city}" class="map-popup__cover" loading="lazy" />
<div class="map-popup__body">
<h3 class="map-popup__city">${loc.city}</h3>
<p class="map-popup__country">${loc.country}</p>
<p class="map-popup__count">${loc.photoCount} photo${loc.photoCount === 1 ? '' : 's'}</p>
<div class="map-popup__albums">${albumLinks}</div>
</div>
</div>
`;
const marker = L.marker([loc.lat, loc.lng], { icon })
.addTo(map)
.bindPopup(popupHtml, { maxWidth: 260, minWidth: 200 });
markers.push(marker);
}
// Fit bounds to show all markers
if (markers.length > 0) {
const group = L.featureGroup(markers);
map.fitBounds(group.getBounds().pad(0.15));
}
setLoading(false);
}
init().catch((err) => {
console.error('[Map] Init error:', err);
if (!cancelled) {
setError('Failed to initialize map');
setLoading(false);
}
});
return () => {
cancelled = true;
if (mapRef.current) {
(mapRef.current as L.Map).remove();
mapRef.current = null;
}
};
}, []);
if (error) {
return (
<div className="map-container__loading">
<p>{error}</p>
</div>
);
}
return (
<>
{loading && (
<div className="map-container__loading">
<p>Loading map…</p>
</div>
)}
<div
ref={containerRef}
className="map-container"
style={{ display: loading ? 'none' : 'block' }}
/>
</>
);
}

3
content/gallery.yaml
View File

@@ -33,3 +33,6 @@ footer:
instagram: quasiralf
# email: hello@example.com
# website: https://example.com
# Enable the /map page
map: true

3
content/gallery.yaml.example
View File

@@ -20,6 +20,9 @@ albums:
# Show camera/lens EXIF on photo hover (default: true)
# exifOnHover: false
# Enable the /map page — plots photos on a world map by city/country (default: false)
# map: true
# Photo grid layout — customize columns, gap, aspect ratio, and mode.
# grid:
# columns: 3 # default: 3

4
lib/config.ts
View File

@@ -123,6 +123,7 @@ interface GalleryYaml {
hero?: string | string[];
albums?: string[];
exifOnHover?: boolean;
map?: boolean;
theme?:
| string
| {
@@ -236,6 +237,8 @@ export interface AppConfig {
theme: ThemeConfig;
/** Footer social links config. */
footer: FooterConfig | null;
/** Show the /map page. Default: false. */
map: boolean;
cacheTtl: number;
rateLimitRpm: number;
}
@@ -392,6 +395,7 @@ export function getConfig(): AppConfig {
website: gallery.footer.website,
}
: null,
map: gallery.map === true,
cacheTtl: env.CACHE_TTL * 1000,
rateLimitRpm: env.RATE_LIMIT_RPM,
};

83
lib/immich.ts
View File

@@ -46,6 +46,8 @@ export interface ImmichExifInfo {
iso: number | null;
exifImageWidth: number | null;
exifImageHeight: number | null;
latitude: number | null;
longitude: number | null;
city: string | null;
state: string | null;
country: string | null;
@@ -53,6 +55,17 @@ export interface ImmichExifInfo {
description: string | null;
}
/** A clustered map marker — one per unique city/country. */
export interface MapLocation {
city: string;
country: string;
lat: number;
lng: number;
photoCount: number;
coverAssetId: string;
albums: { name: string; slug: string; subpageSlug?: string }[];
}
export type ImageSize = 'thumbnail' | 'preview' | 'original';
/** Enriched subpage with album metadata (for rendering cards). */
@@ -312,6 +325,76 @@ class ImmichClient {
return asset;
}
/**
* Aggregate all geotagged photos into location-level markers.
* Returns one entry per unique city+country with averaged lat/lng.
*/
async getMapData(): Promise<MapLocation[]> {
const cacheKey = 'map-data';
const cached = cache.get<MapLocation[]>(cacheKey);
if (cached) return cached;
const albums = await this.getAlbums();
// Build a lookup: album ID → { name, slug, subpageSlug? }
const albumMeta = new Map<string, { name: string; slug: string; subpageSlug?: string }>();
for (const a of albums) {
// Check if this album belongs to a subpage
const sp = this.config.subpages.find((s) => s.albumIds.includes(a.id));
albumMeta.set(a.id, { name: a.albumName, slug: a.slug, subpageSlug: sp?.slug });
}
// Fetch full album data (with assets) for each
const fullAlbums = await Promise.all(albums.map((a) => this.getAlbum(a.id)));
// Bucket assets by city+country
const buckets = new Map<
string,
{ lats: number[]; lngs: number[]; count: number; coverAssetId: string; albumIds: Set<string> }
>();
for (const album of fullAlbums) {
if (!album) continue;
for (const asset of album.assets) {
const exif = asset.exifInfo;
if (!exif?.latitude || !exif?.longitude || !exif?.city || !exif?.country) continue;
const key = `${exif.city}|${exif.country}`;
let bucket = buckets.get(key);
if (!bucket) {
bucket = { lats: [], lngs: [], count: 0, coverAssetId: asset.id, albumIds: new Set() };
buckets.set(key, bucket);
}
bucket.lats.push(exif.latitude);
bucket.lngs.push(exif.longitude);
bucket.count++;
bucket.albumIds.add(album.id);
}
}
// Convert buckets to MapLocation[]
const locations: MapLocation[] = [];
for (const [key, bucket] of buckets) {
const [city, country] = key.split('|');
const lat = bucket.lats.reduce((a, b) => a + b, 0) / bucket.lats.length;
const lng = bucket.lngs.reduce((a, b) => a + b, 0) / bucket.lngs.length;
locations.push({
city,
country,
lat,
lng,
photoCount: bucket.count,
coverAssetId: bucket.coverAssetId,
albums: [...bucket.albumIds]
.map((id) => albumMeta.get(id))
.filter((m): m is NonNullable<typeof m> => !!m),
});
}
cache.set(cacheKey, locations, this.config.cacheTtl);
return locations;
}
/**
* Check if the Immich server is reachable.
*/

4
next.config.ts
View File

@@ -5,9 +5,9 @@ import type { NextConfig } from 'next';
const cspDirectives = [
"default-src 'self'",
"script-src 'self' 'unsafe-inline'",
"style-src 'self' 'unsafe-inline' https://fonts.googleapis.com",
"style-src 'self' 'unsafe-inline' https://fonts.googleapis.com https://unpkg.com",
"font-src 'self' https://fonts.gstatic.com",
"img-src 'self' data:",
"img-src 'self' data: https://*.basemaps.cartocdn.com",
"connect-src 'self'",
"frame-ancestors 'none'",
"base-uri 'self'",

23
package-lock.json generated
View File

@@ -8,8 +8,10 @@
"name": "immich-lightbox",
"version": "0.1.0",
"dependencies": {
"@types/leaflet": "^1.9.21",
"gray-matter": "^4.0.3",
"js-yaml": "^4.1.1",
"leaflet": "^1.9.4",
"next": "16.1.6",
"react": "19.2.3",
"react-dom": "19.2.3",
@@ -2112,6 +2114,12 @@
"dev": true,
"license": "MIT"
},
"node_modules/@types/geojson": {
"version": "7946.0.16",
"resolved": "https://registry.npmjs.org/@types/geojson/-/geojson-7946.0.16.tgz",
"integrity": "sha512-6C8nqWur3j98U6+lXDfTUWIfgvZU+EumvpHKcYjujKH7woYyLj2sUmff0tRhrqM7BohUw7Pz3ZB1jj2gW9Fvmg==",
"license": "MIT"
},
"node_modules/@types/js-yaml": {
"version": "4.0.9",
"resolved": "https://registry.npmjs.org/@types/js-yaml/-/js-yaml-4.0.9.tgz",
@@ -2133,6 +2141,15 @@
"dev": true,
"license": "MIT"
},
"node_modules/@types/leaflet": {
"version": "1.9.21",
"resolved": "https://registry.npmjs.org/@types/leaflet/-/leaflet-1.9.21.tgz",
"integrity": "sha512-TbAd9DaPGSnzp6QvtYngntMZgcRk+igFELwR2N99XZn7RXUdKgsXMR+28bUO0rPsWp8MIu/f47luLIQuSLYv/w==",
"license": "MIT",
"dependencies": {
"@types/geojson": "*"
}
},
"node_modules/@types/node": {
"version": "20.19.33",
"resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.33.tgz",
@@ -5512,6 +5529,12 @@
"node": ">=0.10"
}
},
"node_modules/leaflet": {
"version": "1.9.4",
"resolved": "https://registry.npmjs.org/leaflet/-/leaflet-1.9.4.tgz",
"integrity": "sha512-nxS1ynzJOmOlHp+iL3FyWqK89GtNL8U8rvlMOsQdTTssxZwCXh8N2NB3GDQOL+YR3XnWyZAxwQixURb+FA74PA==",
"license": "BSD-2-Clause"
},
"node_modules/levn": {
"version": "0.4.1",
"resolved": "https://registry.npmjs.org/levn/-/levn-0.4.1.tgz",

2
package.json
View File

@@ -15,8 +15,10 @@
"test:e2e": "playwright test"
},
"dependencies": {
"@types/leaflet": "^1.9.21",
"gray-matter": "^4.0.3",
"js-yaml": "^4.1.1",
"leaflet": "^1.9.4",
"next": "16.1.6",
"react": "19.2.3",
"react-dom": "19.2.3",

16
plans/IDEAS.md
View File

@@ -10,6 +10,17 @@
- **Photo stories / Essays** — Vertical scroll format with images + text interspersed, like a photo essay. Portfolio differentiator
- **Map view** — Minimal world map from EXIF city/country data, each dot links to an album. Mapbox GL or Leaflet
- **Collections by camera/lens** — Auto-generate virtual albums from EXIF data ("Shot on Leica Q3", "Summilux 35mm")
- **Client proofing** — Let clients favorite/select photos in password-protected galleries. Extends existing password gate
- **Download originals** — Button in lightbox to download full-res, proxied through server (keeps Immich hidden). Unlocks client delivery
- **Before/After slider** — Drag-to-reveal comparison component for retouching/editing showcases
- **Print shop integration** — "Buy Print" button linking to external print-on-demand service or contact form with photo reference
- **Watermarking** — Server-side watermark overlay on proxied images (corner logo, center text, or diagonal). Configurable in YAML
- **Curated homepage feed** — Hand-picked "best of" sequence across all albums, like an Instagram highlights page
- **Photo of the Day** — Auto-rotate hero image daily from a designated favorites album. Gives visitors a reason to return
- **EXIF analytics page** — Visual breakdown of shooting patterns: most-used focal lengths, aperture distribution, camera body stats
- **Color palette extraction** — Show dominant colors per photo/album as subtle accents. Art direction + bespoke feel
- **Timeline / Year view** — Chronological scroll of all work by year/month, showing progression over time
- **Search by EXIF** — Filter entire portfolio by camera settings ("everything at f/1.4", "all black & white")
## 👤 User / Visitor
@@ -27,9 +38,14 @@
| Slideshow mode | Low | High — exhibition ready |
| Fullscreen API in lightbox | Low | Medium — immersive |
| Monochrome toggle | Low | Medium — Leica vibes |
| Download originals | Low | High — client delivery |
| ISR caching | Medium | High — performance |
| Photo of the Day | Low | Medium — return visits |
| Before/After slider | Medium | Medium — editing showcase |
| Photo stories/essays | High | Very high — differentiator |
| Map view | Medium | High — wow factor |
| Client proofing | High | Very high — business tool |
| EXIF analytics | Medium | Medium — gear-nerd appeal |
## ✅ Already Implemented