experimental: portfolio features (justified layout, unlisted pages, captions, per-album grid, focal point, nav links, cover hero) (#431)

## Was ist das? Sieben neue Portfolio-Features, alle als **experimental** gekennzeichnet — in YAML-Kommentaren, Admin-Panel-Labels und Commit-Scopes, damit sie einzeln nachvollziehbar und revertierbar bleiben. ## Features (je ein Commit) | Commit | Feature | | --- | --- | | `justified rows gallery layout` | Neues Grid-Layout `justified`: zeilenbasiert, gleiche Höhen, volle Breite — Flexbox ohne JS-Messung, letzte Zeile bleibt natürlich klein | | `hide subpages from navigation` | `hidden: true`: Seite aus Nav/Homepage raus, per Direktlink erreichbar — im Gegensatz zu `enabled: false` (404) | | `lightbox captions` | Immich-Asset-Description als Bildunterschrift im Info-Panel; EXIF-Route liefert bei `exifOnHover: false` jetzt nur noch die Caption statt 403 | | `per-album grid overrides` | `grid:` pro Album-Eintrag, Präzedenz global < Subpage < Album | | `per-album cover focal point` | `coverPosition:` → `object-position` auf Cover-Karten, strikt validiert | | `external links in header navigation` | `navLinks:` in settings.yaml, nur http(s), sanitisiert | | `cover splash hero style` | `heroStyle: cover`: Fullscreen-Splash mit Enter-Link ins Portfolio | Alle Optionen sind im Admin-Panel editierbar (PageBuilder / SettingsEditor). ## Tests - 356 Unit-Tests grün (13 neue: deriveGallery hidden/grid/coverPosition, sanitizeNavLinks, EXIF-Route-Captions, justified-Layout-Validierung) - `npx tsc --noEmit`: 0 Fehler - `npm run build`: sauber - Justified-Zeilenmathematik und Cover-Splash per Browser-Harness visuell/numerisch verifiziert (volle Zeilen enden exakt an der Containerkante, letzte Zeile bleibt natürlich) --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: ralksta <ralksta@users.noreply.github.com> Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: lancetm714 <108419425+lancetm714@users.noreply.github.com>
2026-08-14 17:56:22 +02:00
parent 2fe1157a5d
commit 84c7eeef40
24 changed files with 916 additions and 84 deletions
--- a/lib/tests/config.test.ts
+++ b/lib/tests/config.test.ts
@@ -12,7 +12,38 @@ vi.mock('@/lib/env', () => ({
  },
 }));

-import { slugify, buildSubpageGrid } from '@/lib/config';
+import { slugify, buildSubpageGrid, sanitizeNavLinks } from '@/lib/config';
+
+// EXPERIMENTAL: external navigation links — rendered as <a href> in the
+// header, so only http(s) URLs may survive sanitisation.
+describe('sanitizeNavLinks', () => {
+  it('keeps well-formed http(s) links', () => {
+    expect(
+      sanitizeNavLinks([
+        { label: 'Shop', url: 'https://shop.example.com' },
+        { label: 'Blog', url: 'http://blog.example.com/a?b=c' },
+      ]),
+    ).toEqual([
+      { label: 'Shop', url: 'https://shop.example.com' },
+      { label: 'Blog', url: 'http://blog.example.com/a?b=c' },
+    ]);
+  });
+
+  it('drops non-http schemes and entries without label or url', () => {
+    expect(
+      sanitizeNavLinks([
+        { label: 'Bad', url: 'javascript:alert(1)' },
+        { label: 'AlsoBad', url: 'data:text/html,x' },
+        { label: '', url: 'https://x.example' },
+        { label: 'NoUrl', url: '' },
+      ]),
+    ).toEqual([]);
+  });
+
+  it('returns empty for undefined input', () => {
+    expect(sanitizeNavLinks(undefined)).toEqual([]);
+  });
+});

 describe('slugify', () => {
  it('converts a simple name to lowercase with hyphens', () => {
@@ -79,6 +110,12 @@ describe('buildSubpageGrid', () => {
    });
  });

+  it('preserves the experimental justified layout', () => {
+    expect(buildSubpageGrid({ layout: 'justified' })).toEqual({
+      grid: { layout: 'justified' },
+    });
+  });
+
  it('falls back to masonry for an unknown layout', () => {
    expect(buildSubpageGrid({ layout: 'unknown-layout' })).toEqual({
      grid: { layout: 'masonry' },
--- a/lib/tests/derive-gallery.test.ts
+++ b/lib/tests/derive-gallery.test.ts
@@ -156,6 +156,66 @@ describe('deriveGallery accepts valid structures', () => {
    expect(result.albumManualOrders[A]).toEqual([B]);
  });

+  // EXPERIMENTAL: hidden keeps a subpage reachable by direct link while
+  // removing it from navigation — distinct from enabled:false, which 404s.
+  it('derives the hidden flag on array-style subpages', () => {
+    const result = deriveGallery({
+      subpages: [{ name: 'Preview', hidden: true, albums: [A] }],
+    } as unknown as GalleryYaml);
+
+    expect(result.subpages[0].hidden).toBe(true);
+    expect(result.subpages[0].enabled).toBe(true);
+  });
+
+  it('derives the hidden flag on map-style subpages, defaulting to falsy', () => {
+    const result = deriveGallery({
+      subpages: { Preview: { hidden: true, albums: [A] }, Open: [B] },
+    } as unknown as GalleryYaml);
+
+    const preview = result.subpages.find((sp) => sp.name === 'Preview');
+    const open = result.subpages.find((sp) => sp.name === 'Open');
+    expect(preview?.hidden).toBe(true);
+    expect(open?.hidden).toBeFalsy();
+  });
+
+  // EXPERIMENTAL: per-album grid overrides — merged over subpage/global grid.
+  it('collects per-album grid overrides, dropping unknown layouts to masonry', () => {
+    const result = deriveGallery({
+      albums: [
+        { [A]: { title: 'Panoramas', grid: { layout: 'filmstrip', columns: 2 } } },
+        { [B]: { grid: { layout: 'not-a-layout' } } },
+      ],
+    } as unknown as GalleryYaml);
+
+    expect(result.albumGrids[A]).toEqual({ layout: 'filmstrip', columns: 2 });
+    expect(result.albumGrids[B]).toEqual({ layout: 'masonry' });
+  });
+
+  it('leaves albumGrids empty for entries without a grid', () => {
+    const result = deriveGallery({ albums: [A] } as unknown as GalleryYaml);
+    expect(result.albumGrids).toEqual({});
+  });
+
+  // EXPERIMENTAL: coverPosition feeds object-position on cover images, so it
+  // must be a strict CSS position value — anything else is a typo or an
+  // injection attempt and both should fail loudly.
+  it('collects a valid coverPosition', () => {
+    const result = deriveGallery({
+      albums: [{ [A]: { coverPosition: '50% 25%' } }, { [B]: { coverPosition: 'top' } }],
+    } as unknown as GalleryYaml);
+
+    expect(result.albumCoverPositions[A]).toBe('50% 25%');
+    expect(result.albumCoverPositions[B]).toBe('top');
+  });
+
+  it('rejects a malformed coverPosition, naming the album', () => {
+    expect(() =>
+      deriveGallery({
+        albums: [{ [A]: { coverPosition: 'javascript:alert(1)' } }],
+      } as unknown as GalleryYaml),
+    ).toThrow(new RegExp(A));
+  });
+
  it('ignores an empty asset order rather than storing one', () => {
    const result = deriveGallery({
      albums: [{ [A]: { sort: 'manual', assetOrder: [] } }],
--- a/lib/config/index.ts
+++ b/lib/config/index.ts
@@ -76,6 +76,32 @@ export function buildSubpageGrid(raw?: {
  };
 }

+/**
+ * EXPERIMENTAL: keep only nav links that are safe to render as header <a>
+ * tags. Non-http(s) schemes (javascript:, data:) and incomplete entries are
+ * dropped with a warning rather than throwing — a bad external link should
+ * not take the site down.
+ */
+export function sanitizeNavLinks(
+  raw?: Array<{ label?: string; url?: string }>,
+): Array<{ label: string; url: string }> {
+  if (!raw) return [];
+  const links: Array<{ label: string; url: string }> = [];
+  for (const entry of raw) {
+    const label = entry.label?.trim();
+    const url = entry.url?.trim();
+    if (!label || !url || !/^https?:\/\//i.test(url)) {
+      console.warn(
+        `[Folio] settings.yaml navLinks: dropping entry ${JSON.stringify(entry)} — ` +
+          'label and an http(s) url are required.',
+      );
+      continue;
+    }
+    links.push({ label, url });
+  }
+  return links;
+}
+
 /** The parts of AppConfig that come from gallery.yaml. */
 export interface GalleryDerivation {
  albums: string[];
@@ -87,6 +113,8 @@ export interface GalleryDerivation {
  albumHeroImages: Record<string, string>;
  albumSortModes: Record<string, AlbumSortMode>;
  albumManualOrders: Record<string, string[]>;
+  albumGrids: Record<string, Partial<GridConfig>>;
+  albumCoverPositions: Record<string, string>;
 }

 /**
@@ -108,6 +136,8 @@ export function deriveGallery(gallery: GalleryYaml): GalleryDerivation {
  const albumHeroImages: Record<string, string> = {};
  const albumSortModes: Record<string, AlbumSortMode> = {};
  const albumManualOrders: Record<string, string[]> = {};
+  const albumGrids: Record<string, Partial<GridConfig>> = {};
+  const albumCoverPositions: Record<string, string> = {};

  function processAlbumEntry(
    entry: string | Record<string, string | AlbumEntryObject>,
@@ -162,6 +192,29 @@ export function deriveGallery(gallery: GalleryYaml): GalleryDerivation {
          validateUuid(assetId, `${context} assetOrder[${i}] for album ${validatedUuid}`),
        );
      }
+
+      // EXPERIMENTAL: per-album grid override — reuses the subpage-grid
+      // normalisation so unknown layouts degrade identically.
+      if (value.grid) {
+        const built = buildSubpageGrid(value.grid);
+        if ('grid' in built) albumGrids[validatedUuid] = built.grid;
+      }
+
+      // EXPERIMENTAL: coverPosition lands in a style attribute, so only a
+      // strict CSS position grammar is allowed. Throw like `sort` does — a
+      // silent fallback would leave the owner wondering why nothing moves.
+      if (value.coverPosition != null) {
+        const pos = value.coverPosition.trim();
+        const keyword = /^(center|top|bottom|left|right)( (center|top|bottom|left|right))?$/;
+        const percent = /^\d{1,3}% \d{1,3}%$/;
+        if (!keyword.test(pos) && !percent.test(pos)) {
+          throw new Error(
+            `${context}: album ${validatedUuid} has an invalid coverPosition "${value.coverPosition}". ` +
+              `Use two percentages ("50% 25%") or CSS keywords ("top", "center bottom").`,
+          );
+        }
+        albumCoverPositions[validatedUuid] = pos;
+      }
    }
    return validatedUuid;
  }
@@ -218,6 +271,7 @@ export function deriveGallery(gallery: GalleryYaml): GalleryDerivation {
        essayFile: sp.essayFile,
        essayText: sp.essayText,
        enabled: sp.enabled !== false,
+        hidden: sp.hidden === true,
        ...buildSubpageGrid(sp.grid),
      };
    });
@@ -244,6 +298,7 @@ export function deriveGallery(gallery: GalleryYaml): GalleryDerivation {
        essayFile: sp.essayFile,
        essayText: sp.essayText,
        enabled: sp.enabled !== false,
+        hidden: sp.hidden === true,
        ...buildSubpageGrid(sp.grid),
      };
    });
@@ -262,6 +317,8 @@ export function deriveGallery(gallery: GalleryYaml): GalleryDerivation {
    albumHeroImages,
    albumSortModes,
    albumManualOrders,
+    albumGrids,
+    albumCoverPositions,
  };
 }

@@ -316,6 +373,9 @@ export function getConfig(): AppConfig {
      albumHeroImages: {},
      albumSortModes: {},
      albumManualOrders: {},
+      albumGrids: {},
+      albumCoverPositions: {},
+      navLinks: [],
      cacheTtl: env.CACHE_TTL * 1000,
      staleMaxAge: env.STALE_MAX_AGE * 1000,
      immichTimeoutMs: env.IMMICH_TIMEOUT_MS,
@@ -337,6 +397,8 @@ export function getConfig(): AppConfig {
    albumHeroImages,
    albumSortModes,
    albumManualOrders,
+    albumGrids,
+    albumCoverPositions,
  } = deriveGallery(gallery);

  const siteSeoTitle = settings.seo?.title || settings.title || env.SITE_TITLE || 'Gallery';
@@ -412,6 +474,9 @@ export function getConfig(): AppConfig {
    albumHeroImages,
    albumSortModes,
    albumManualOrders,
+    albumGrids,
+    albumCoverPositions,
+    navLinks: sanitizeNavLinks(settings.navLinks),
    cacheTtl: env.CACHE_TTL * 1000,
    staleMaxAge: env.STALE_MAX_AGE * 1000,
    immichTimeoutMs: env.IMMICH_TIMEOUT_MS,
--- a/lib/config/schema.ts
+++ b/lib/config/schema.ts
@@ -20,6 +20,8 @@ export interface SubpageConfig {
  essayFile?: string;
  essayText?: string;
  enabled?: boolean;
+  /** EXPERIMENTAL: reachable by direct link, but not shown in navigation */
+  hidden?: boolean;
 }

 export interface SubpageObjectValue {
@@ -31,6 +33,8 @@ export interface SubpageObjectValue {
  essayFile?: string;
  essayText?: string;
  enabled?: boolean;
+  /** EXPERIMENTAL: reachable by direct link, but not shown in navigation */
+  hidden?: boolean;
  // Both album lists reuse AlbumEntryObject rather than inlining the shape:
  // the inline copies had already drifted (they never gained `heroImage`), and
  // this path is live for map-style subpages.
@@ -42,6 +46,12 @@ export interface SubpageObjectValue {
  }>;
 }

+/** EXPERIMENTAL: external link shown in the header navigation. */
+export interface NavLinkConfig {
+  label: string;
+  url: string;
+}
+
 export interface FooterConfig {
  name?: string;
  instagram?: string;
@@ -70,14 +80,21 @@ export interface ThemeConfig {
  photoFrame: 'none' | 'passepartout' | 'shadow';
  grain: boolean;
  headerDot: boolean;
-  heroStyle: 'split' | 'fullbleed' | 'minimal' | 'stacked' | 'typographic' | 'mosaic';
+  heroStyle: 'split' | 'fullbleed' | 'minimal' | 'stacked' | 'typographic' | 'mosaic' | 'cover';
 }

 export interface GridConfig {
  columns: number;
  gap: number;
  aspectRatio: string;
-  layout: 'masonry' | 'uniform' | 'showcase' | 'filmstrip' | 'editorial-flow' | 'essay';
+  layout:
+    | 'masonry'
+    | 'uniform'
+    | 'showcase'
+    | 'filmstrip'
+    | 'editorial-flow'
+    | 'essay'
+    | 'justified';
 }

 export interface AppConfig {
@@ -119,6 +136,12 @@ export interface AppConfig {
  albumSortModes: Record<string, AlbumSortMode>;
  /** Pinned asset UUIDs per album for `sort: manual`, in display order. */
  albumManualOrders: Record<string, string[]>;
+  /** EXPERIMENTAL: per-album grid overrides, merged over the subpage/global grid. */
+  albumGrids: Record<string, Partial<GridConfig>>;
+  /** EXPERIMENTAL: per-album focal point for cover crops (CSS object-position). */
+  albumCoverPositions: Record<string, string>;
+  /** EXPERIMENTAL: external links appended to the header navigation. */
+  navLinks: NavLinkConfig[];
  cacheTtl: number;
  /** How long (ms) an expired cache entry may still be served while Immich is unreachable. */
  staleMaxAge: number;
@@ -152,6 +175,10 @@ export interface AlbumEntryObject {
  sort?: string;
  /** Pinned asset UUIDs for `sort: manual`. Everything else follows automatically. */
  assetOrder?: string[];
+  /** EXPERIMENTAL: per-album grid override, merged over the subpage/global grid */
+  grid?: { columns?: number; gap?: number; aspectRatio?: string; layout?: string };
+  /** EXPERIMENTAL: focal point for the cover crop, e.g. "50% 25%" or "top" */
+  coverPosition?: string;
 }

 export interface GalleryYaml {
@@ -174,6 +201,7 @@ export interface GalleryYaml {
        essayFile?: string;
        essayText?: string;
        enabled?: boolean;
+        hidden?: boolean;
        grid?: {
          columns?: number;
          gap?: number;
@@ -223,6 +251,8 @@ export interface SettingsYaml {
  };
  footer?: FooterConfig;
  legal?: Partial<LegalConfig>;
+  /** EXPERIMENTAL: external links appended to the header navigation. */
+  navLinks?: Array<{ label?: string; url?: string }>;
  protection?: {
    disableRightClick?: boolean;
    disableImageDrag?: boolean;
--- a/lib/config/theme.ts
+++ b/lib/config/theme.ts
@@ -81,8 +81,17 @@ export const VALID_HERO_STYLES = [
  'stacked',
  'typographic',
  'mosaic',
+  'cover', // EXPERIMENTAL: fullscreen splash with a single "Enter" link
+];
+export const VALID_LAYOUTS = [
+  'masonry',
+  'uniform',
+  'showcase',
+  'filmstrip',
+  'editorial-flow',
+  'essay',
+  'justified', // EXPERIMENTAL: row-based layout with equal heights
 ];
-export const VALID_LAYOUTS = ['masonry', 'uniform', 'showcase', 'filmstrip', 'editorial-flow', 'essay'];

 export function resolveTheme(raw?: SettingsYaml['theme']): ThemeConfig {
  if (!raw) return { ...THEME_PRESETS.studio };
--- a/lib/immich.ts
+++ b/lib/immich.ts
@@ -461,7 +461,12 @@ class ImmichClient {
   * Get enriched subpage summaries for the homepage.
   */
  async getSubpages(forceFresh = false): Promise<SubpageSummary[]> {
-    const activeSubpages = this.config.subpages.filter((sp) => sp.enabled !== false);
+    // hidden (EXPERIMENTAL) drops a subpage from every list this feeds (nav,
+    // homepage, hero) while getSubpageAlbums()/isValidSubpage() still resolve
+    // it — unlike enabled:false, which 404s the page entirely.
+    const activeSubpages = this.config.subpages.filter(
+      (sp) => sp.enabled !== false && sp.hidden !== true,
+    );
    if (activeSubpages.length === 0) return [];

    const albums = await this.getAlbums(forceFresh);