From f8c83bc1f410c75aba2b023eb9e8ddade37cc9a2 Mon Sep 17 00:00:00 2001 From: Alan Grainger <16197738+alangrainger@users.noreply.github.com> Date: Mon, 27 Jul 2026 12:14:19 +1200 Subject: [PATCH] #273 refinements: match Immich date display, fix timeline UTC parsing, rename timezone flag --- app/config.json | 2 +- app/public/style.css | 3 - app/src/client/layout.ts | 11 ++-- app/src/client/sidebar.ts | 107 ++++++++++++++++++++++---------- app/src/gallery/exif.ts | 2 +- app/src/immich.ts | 9 ++- app/tests/assetMetadata.test.ts | 4 +- app/tests/localDateTime.test.ts | 46 ++++++++++++++ app/tests/migrations.test.ts | 2 +- app/tests/sidebarDate.test.ts | 32 ++++++++-- docs/config/gallery.md | 2 +- docs/config/metadata.md | 10 +-- docs/installation.md | 3 + 13 files changed, 174 insertions(+), 59 deletions(-) create mode 100644 app/tests/localDateTime.test.ts diff --git a/app/config.json b/app/config.json index 86d6464..a4a96d2 100644 --- a/app/config.json +++ b/app/config.json @@ -18,7 +18,7 @@ }, "exif": { "dateTimeOriginal": false, - "timeZone": false, + "timezone": false, "fileName": false, "dimensions": false, "fileSize": false, diff --git a/app/public/style.css b/app/public/style.css index 2deae5d..9738ebc 100644 --- a/app/public/style.css +++ b/app/public/style.css @@ -523,9 +523,6 @@ html.ipp-sidebar-open .ipp-sidebar { opacity: 0.8; } -.ipp-sidebar-date { - padding: 12px 0; -} .ipp-sidebar-date-primary { font-weight: 500; } diff --git a/app/src/client/layout.ts b/app/src/client/layout.ts index fe54a35..5d75a9d 100644 --- a/app/src/client/layout.ts +++ b/app/src/client/layout.ts @@ -100,12 +100,11 @@ function dateLabel (key: string, mode: GroupByDateMode): string { if (!y || !m) return key // Intl.DateTimeFormat picks up the browser's locale; UTC timeZone keeps the // displayed date consistent with the bucket key (which is already local). - return new Intl.DateTimeFormat(undefined, { - year: 'numeric', - month: 'long', - ...(mode === 'day' ? { day: 'numeric' } : {}), - timeZone: 'UTC' - }).format(new Date(Date.UTC(y, m - 1, mode === 'day' ? (d || 1) : 1))) + // Day headers use Immich's timeline format ("Sat, 18 Oct 2025"). + return new Intl.DateTimeFormat(undefined, mode === 'day' + ? { weekday: 'short', day: 'numeric', month: 'short', year: 'numeric', timeZone: 'UTC' } + : { month: 'long', year: 'numeric', timeZone: 'UTC' } + ).format(new Date(Date.UTC(y, m - 1, mode === 'day' ? (d || 1) : 1))) } /** diff --git a/app/src/client/sidebar.ts b/app/src/client/sidebar.ts index 84e5590..f87433a 100644 --- a/app/src/client/sidebar.ts +++ b/app/src/client/sidebar.ts @@ -143,7 +143,7 @@ function renderContents (root: HTMLElement, item: GalleryItem | undefined) { const exif = item.exif if (exif && hasAnyExifField(exif)) { - root.appendChild(renderSection('details', ...renderDetailRows(exif))) + root.appendChild(renderSection('details', ...renderDetailRows(exif, item))) } if (exif && hasAnyLocationField(exif)) { @@ -192,7 +192,7 @@ function renderDescription (description: string): HTMLElement { return el } -function renderDetailRows (exif: GalleryExif): HTMLElement[] { +function renderDetailRows (exif: GalleryExif, item: GalleryItem): HTMLElement[] { const heading = document.createElement('h3') heading.className = 'ipp-sidebar-heading' heading.textContent = 'Details' @@ -200,7 +200,7 @@ function renderDetailRows (exif: GalleryExif): HTMLElement[] { const rows: HTMLElement[] = [heading] if (exif.dateTimeOriginal) { - rows.push(renderDateRow(exif.dateTimeOriginal, exif.timeZone)) + rows.push(renderDateRow(exif.dateTimeOriginal, exif.timeZone, item.localDateTime)) } const fileRow = renderFileRow(exif) if (fileRow) rows.push(fileRow) @@ -212,11 +212,20 @@ function renderDetailRows (exif: GalleryExif): HTMLElement[] { return rows } -function renderDateRow (iso: string, timeZone?: string): HTMLElement { +function renderDateRow (iso: string, timeZone?: string, localDateTime?: string): HTMLElement { const row = makeRow(ICON_CALENDAR) row.classList.add('ipp-sidebar-date') const body = row.querySelector('.ipp-sidebar-row-body') as HTMLElement - const formatted = formatDate(iso, timeZone) + // Mirror Immich's DetailPanelDate: with a photo timezone, show the capture + // instant in that zone (with its UTC offset); without one, show the + // photographer's wall-clock (localDateTime) rather than converting the + // instant into the viewer's timezone - keeping the sidebar consistent with + // the date-group headers, which bucket by the same wall-clock. + const formatted = timeZone + ? formatDate(iso, timeZone) + : localDateTime + ? formatWallClock(localDateTime) + : formatDate(iso) const date = document.createElement('p') date.className = 'ipp-sidebar-date-primary' date.textContent = formatted.date @@ -396,52 +405,84 @@ export interface FormattedDate { time: string } -export function formatDate (iso: string, timeZone?: string): FormattedDate { +/** + * Format a capture timestamp for the sidebar date row, in the photo's own + * timezone when one is provided (and enabled server-side). + * + * `locales` follows the browser locale when undefined; tests pass 'en-US' + * so assertions don't depend on the machine running them. + */ +export function formatDate (iso: string, timeZone?: string, locales?: string): FormattedDate { const d = new Date(iso) if (isNaN(d.getTime())) return { date: iso, time: '' } if (timeZone) { - try { + if (canFormat({ timeZone })) { + // A zone Intl understands (IANA name or "+08:00" style). Show the UTC + // offset too, on browsers that support rendering it. + const timeOptions = canFormat({ timeZone, timeZoneName: 'longOffset' }) + ? { ...TIME_FORMAT_OPTIONS, timeZone, timeZoneName: 'longOffset' as const } + : { ...TIME_FORMAT_OPTIONS, timeZone } return { - date: new Intl.DateTimeFormat(undefined, { ...DATE_FORMAT_OPTIONS, timeZone }).format(d), - time: new Intl.DateTimeFormat(undefined, { - ...TIME_FORMAT_OPTIONS, - timeZone, - timeZoneName: 'longOffset' - }).format(d) - } - } catch (e) { - const offsetMinutes = parseFixedOffset(timeZone) - if (offsetMinutes != null) { - const localWallClock = new Date(d.getTime() + offsetMinutes * 60_000) - return { - date: new Intl.DateTimeFormat(undefined, { ...DATE_FORMAT_OPTIONS, timeZone: 'UTC' }).format(localWallClock), - time: new Intl.DateTimeFormat(undefined, { ...TIME_FORMAT_OPTIONS, timeZone: 'UTC' }).format(localWallClock) + - ' ' + formatFixedOffset(offsetMinutes) - } + date: new Intl.DateTimeFormat(locales, { ...DATE_FORMAT_OPTIONS, timeZone }).format(d), + time: new Intl.DateTimeFormat(locales, timeOptions).format(d) } + } - try { - return { - date: new Intl.DateTimeFormat(undefined, { ...DATE_FORMAT_OPTIONS, timeZone }).format(d), - time: new Intl.DateTimeFormat(undefined, { ...TIME_FORMAT_OPTIONS, timeZone }).format(d) - } - } catch (e) { - // Invalid/unknown timezone: retain the previous browser-local fallback. + // Fixed-offset values from Immich ("UTC+8") that Intl rejects: shift the + // instant manually and append the offset label ourselves. Anything else + // unrecognised falls through to browser-local formatting. + const offsetMinutes = parseFixedOffset(timeZone) + if (offsetMinutes != null) { + const localWallClock = new Date(d.getTime() + offsetMinutes * 60_000) + return { + date: new Intl.DateTimeFormat(locales, { ...DATE_FORMAT_OPTIONS, timeZone: 'UTC' }).format(localWallClock), + time: new Intl.DateTimeFormat(locales, { ...TIME_FORMAT_OPTIONS, timeZone: 'UTC' }).format(localWallClock) + + ' ' + formatFixedOffset(offsetMinutes) } } } try { return { - date: new Intl.DateTimeFormat(undefined, DATE_FORMAT_OPTIONS).format(d), - time: new Intl.DateTimeFormat(undefined, TIME_FORMAT_OPTIONS).format(d) + date: new Intl.DateTimeFormat(locales, DATE_FORMAT_OPTIONS).format(d), + time: new Intl.DateTimeFormat(locales, TIME_FORMAT_OPTIONS).format(d) } - } catch (e) { + } catch { return { date: iso, time: '' } } } +/** + * Format a timezone-agnostic wall-clock timestamp (Immich's `localDateTime`, + * whose `Z` suffix is nominal) exactly as written, with no offset label - + * every viewer sees what the camera clock showed. + */ +export function formatWallClock (iso: string, locales?: string): FormattedDate { + const d = new Date(iso) + if (isNaN(d.getTime())) return { date: iso, time: '' } + try { + return { + date: new Intl.DateTimeFormat(locales, { ...DATE_FORMAT_OPTIONS, timeZone: 'UTC' }).format(d), + time: new Intl.DateTimeFormat(locales, { ...TIME_FORMAT_OPTIONS, timeZone: 'UTC' }).format(d) + } + } catch { + return { date: iso, time: '' } + } +} + +/** + * True when this browser's Intl accepts the given DateTimeFormat options - + * unknown timezones and unsupported `timeZoneName` values throw. + */ +function canFormat (options: Intl.DateTimeFormatOptions): boolean { + try { + return !!new Intl.DateTimeFormat(undefined, options) + } catch { + return false + } +} + function parseFixedOffset (timeZone: string): number | null { const match = /^(?:UTC|GMT)([+-])(\d{1,2})(?::?(\d{2}))?$/i.exec(timeZone.trim()) if (!match) return null diff --git a/app/src/gallery/exif.ts b/app/src/gallery/exif.ts index bb69799..9ee59bf 100644 --- a/app/src/gallery/exif.ts +++ b/app/src/gallery/exif.ts @@ -81,7 +81,7 @@ const EXIF_RULES: FieldRule[] = [ if (info.dateTimeOriginal) { out.dateTimeOriginal = info.dateTimeOriginal // Never expose the timezone independently of the opted-in date. - if (fieldFlag('exif', 'timeZone') && info.timeZone) out.timeZone = info.timeZone + if (fieldFlag('exif', 'timezone') && info.timeZone) out.timeZone = info.timeZone } } }, diff --git a/app/src/immich.ts b/app/src/immich.ts index 1f1584d..c965bd0 100644 --- a/app/src/immich.ts +++ b/app/src/immich.ts @@ -381,9 +381,14 @@ function ratioToDimensions (ratio: number): { width: number, height: number } { * time portion reads as the photographer's local wall-clock (the `Z` suffix is * nominal, as with Immich's own `localDateTime`). Undefined if no timestamp. */ -function localDateTimeFromOffset (fileCreatedAt?: string, offsetHours?: number): string | undefined { +export function localDateTimeFromOffset (fileCreatedAt?: string, offsetHours?: number): string | undefined { if (!fileCreatedAt) return undefined - const ms = Date.parse(fileCreatedAt) + // The timeline bucket API serialises fileCreatedAt as a zone-less UTC + // string ('2024-12-11T07:41:54'). Date.parse treats a zone-less date-time + // as SERVER-LOCAL time, which would skew every date by the server's UTC + // offset (e.g. 12h early on a UTC+12 host) - pin it to UTC explicitly. + const utc = /(?:[Zz]|[+-]\d{2}:?\d{2})$/.test(fileCreatedAt) ? fileCreatedAt : fileCreatedAt + 'Z' + const ms = Date.parse(utc) if (isNaN(ms)) return undefined return new Date(ms + (offsetHours || 0) * 3600_000).toISOString() } diff --git a/app/tests/assetMetadata.test.ts b/app/tests/assetMetadata.test.ts index acda187..77a34e2 100644 --- a/app/tests/assetMetadata.test.ts +++ b/app/tests/assetMetadata.test.ts @@ -97,7 +97,7 @@ describe('buildAssetMetadata', () => { }) it('returns the photo timezone only when both date and timezone are enabled', () => { - setConfig({ ipp: { showMetadata: { exif: { dateTimeOriginal: true, timeZone: true } } } }) + setConfig({ ipp: { showMetadata: { exif: { dateTimeOriginal: true, timezone: true } } } }) const meta = buildAssetMetadata(asset(), share()) expect(meta.exif?.dateTimeOriginal).toBe('2025-10-18T06:28:54.000Z') expect(meta.exif?.timeZone).toBe('Asia/Singapore') @@ -105,7 +105,7 @@ describe('buildAssetMetadata', () => { setConfig({ ipp: { showMetadata: { exif: { dateTimeOriginal: true } } } }) expect(buildAssetMetadata(asset(), share()).exif?.timeZone).toBeUndefined() - setConfig({ ipp: { showMetadata: { exif: { timeZone: true } } } }) + setConfig({ ipp: { showMetadata: { exif: { timezone: true } } } }) expect(buildAssetMetadata(asset(), share()).exif).toBeUndefined() }) diff --git a/app/tests/localDateTime.test.ts b/app/tests/localDateTime.test.ts new file mode 100644 index 0000000..fab4497 --- /dev/null +++ b/app/tests/localDateTime.test.ts @@ -0,0 +1,46 @@ +import { describe, it, expect, beforeAll, afterAll } from 'vitest' +import { localDateTimeFromOffset } from '../src/immich' + +/* + Regression test for the timeline date-grouping skew: Immich's timeline + bucket API returns fileCreatedAt as a zone-less UTC string + ('2024-12-11T07:41:54'), which Date.parse treats as server-local time. + On a non-UTC host every reconstructed localDateTime shifted by the + host's UTC offset, putting assets under the wrong date-group header + (e.g. a "10 Dec" header over photos whose sidebar said 11 Dec). + + TZ is pinned to a far-from-UTC zone so the suite fails if the parse + ever becomes host-local again, regardless of the machine running it. +*/ + +const originalTz = process.env.TZ + +beforeAll(() => { + process.env.TZ = 'Pacific/Auckland' // UTC+12/+13 +}) + +afterAll(() => { + if (originalTz === undefined) delete process.env.TZ + else process.env.TZ = originalTz +}) + +describe('localDateTimeFromOffset', () => { + it('treats zone-less timeline timestamps as UTC, not server-local', () => { + expect(localDateTimeFromOffset('2024-12-11T07:41:54', 0)).toBe('2024-12-11T07:41:54.000Z') + }) + + it('applies the photographer offset to the UTC instant', () => { + expect(localDateTimeFromOffset('2024-12-10T15:30:00', 8)).toBe('2024-12-10T23:30:00.000Z') + expect(localDateTimeFromOffset('2024-12-11T03:30:00', -8)).toBe('2024-12-10T19:30:00.000Z') + }) + + it('leaves explicitly zoned timestamps alone', () => { + expect(localDateTimeFromOffset('2024-12-11T07:41:54Z', 0)).toBe('2024-12-11T07:41:54.000Z') + expect(localDateTimeFromOffset('2024-12-11T07:41:54+00:00', 0)).toBe('2024-12-11T07:41:54.000Z') + }) + + it('returns undefined for missing or invalid input', () => { + expect(localDateTimeFromOffset(undefined, 0)).toBeUndefined() + expect(localDateTimeFromOffset('not-a-date', 0)).toBeUndefined() + }) +}) diff --git a/app/tests/migrations.test.ts b/app/tests/migrations.test.ts index cb25c2d..eaa3946 100644 --- a/app/tests/migrations.test.ts +++ b/app/tests/migrations.test.ts @@ -186,7 +186,7 @@ describe('metadataEnabled shim', () => { const exif = ((config.ipp as Record).showMetadata as Record).exif as Record expect(exif.enabled).toBeUndefined() expect(exif.dateTimeOriginal).toBe(true) - expect(exif.timeZone).toBeUndefined() + expect(exif.timezone).toBeUndefined() expect(exif.fileName).toBe(true) expect(exif.dimensions).toBe(true) expect(exif.fileSize).toBe(true) diff --git a/app/tests/sidebarDate.test.ts b/app/tests/sidebarDate.test.ts index 7e22113..3c8850d 100644 --- a/app/tests/sidebarDate.test.ts +++ b/app/tests/sidebarDate.test.ts @@ -1,11 +1,14 @@ import { describe, expect, it } from 'vitest' -import { formatDate } from '../src/client/sidebar' +import { formatDate, formatWallClock } from '../src/client/sidebar' + +// The locale is pinned to en-US throughout: formatDate follows the system +// locale by default, which would make these assertions machine-dependent. describe('sidebar date formatting', () => { const capturedAt = '2025-10-18T06:28:54.000Z' it('formats the capture instant in the photo IANA timezone', () => { - const formatted = formatDate(capturedAt, 'Asia/Singapore') + const formatted = formatDate(capturedAt, 'Asia/Singapore', 'en-US') expect(formatted.date).toBe('Oct 18, 2025') expect(formatted.time).toContain('Sat') expect(formatted.time).toContain('2:28:54 PM') @@ -13,13 +16,34 @@ describe('sidebar date formatting', () => { }) it('supports legacy fixed-offset timezones from Immich', () => { - const formatted = formatDate(capturedAt, 'UTC+8') + const formatted = formatDate(capturedAt, 'UTC+8', 'en-US') expect(formatted.date).toBe('Oct 18, 2025') expect(formatted.time).toContain('2:28:54 PM') expect(formatted.time).toContain('GMT+08:00') }) + it('falls back to local formatting for an unknown timezone', () => { + const formatted = formatDate(capturedAt, 'Not/AZone', 'en-US') + expect(formatted.date).toMatch(/Oct 1[78], 2025/) + expect(formatted.time).toContain(':28:54') + }) + it('retains the original value when the timestamp is invalid', () => { - expect(formatDate('not-a-date', 'Asia/Singapore')).toEqual({ date: 'not-a-date', time: '' }) + expect(formatDate('not-a-date', 'Asia/Singapore', 'en-US')).toEqual({ date: 'not-a-date', time: '' }) + }) +}) + +describe('sidebar wall-clock formatting', () => { + // localDateTime carries the photographer's wall-clock with a nominal Z; + // it must render exactly as written, with no offset label, for any viewer. + it('renders the wall-clock as written with no offset label', () => { + const formatted = formatWallClock('2024-12-10T23:30:00.000Z', 'en-US') + expect(formatted.date).toBe('Dec 10, 2024') + expect(formatted.time).toContain('11:30:00 PM') + expect(formatted.time).not.toContain('GMT') + }) + + it('retains the original value when the timestamp is invalid', () => { + expect(formatWallClock('not-a-date', 'en-US')).toEqual({ date: 'not-a-date', time: '' }) }) }) diff --git a/docs/config/gallery.md b/docs/config/gallery.md index 1d2eebb..cb70afd 100644 --- a/docs/config/gallery.md +++ b/docs/config/gallery.md @@ -73,7 +73,7 @@ Group the gallery's thumbnails by date, with a header above each group. - `false` - no grouping (default). - `"month"` - month headers like "December 2024". -- `"day"` - day headers like "25 December 2024". +- `"day"` - day headers like "Wed, 25 Dec 2024" (matching Immich's own timeline format). Grouping uses each photo's local "taken" date (matching Immich's own timeline), and sorts photos newest-first. Items missing a creation date end up under an "Undated" bucket at the end (or render without any header when the whole gallery is undated). diff --git a/docs/config/metadata.md b/docs/config/metadata.md index c7fdab4..d5fcea7 100644 --- a/docs/config/metadata.md +++ b/docs/config/metadata.md @@ -13,7 +13,7 @@ Show the description in the sidebar only (not as a lightbox caption), expose cam "description": { "caption": false, "sidebar": true }, "exif": { "dateTimeOriginal": true, - "timeZone": true, + "timezone": true, "make": true, "model": true, "lensModel": true, @@ -40,7 +40,7 @@ Every per-field flag defaults to `false`. A field is sent to the client only whe The share owner's **"Show metadata"** toggle in Immich takes precedence over everything here: when it's off, IPP suppresses all description / EXIF / location output and hides the info sidebar (and its toolbar toggle) entirely, regardless of these settings. Note that with "Show metadata" off Immich also strips file creation dates from non-album shares, so [date grouping](/config/gallery#groupbydate) won't work for those shares. -The info sidebar (and its toolbar toggle button) only appear when there is at least one section the operator has opted into - i.e. `description.sidebar` is true, or `exif` / `location` has at least one displayable field set to `true`. Dependent flags such as `exif.timeZone` do not activate the sidebar on their own. With all three groups off, the sidebar UI is suppressed. +The info sidebar (and its toolbar toggle button) only appear when there is at least one section the operator has opted into - i.e. `description.sidebar` is true, or `exif` / `location` has at least one displayable field set to `true`. Dependent flags such as `exif.timezone` do not activate the sidebar on their own. With all three groups off, the sidebar UI is suppressed. ## Description @@ -59,8 +59,8 @@ Under `ipp.showMetadata.exif`. Every flag defaults to `false`. | Option | Type | Description | |--------------------|--------|------------------------------------------------------------------------------------------------------------------| -| `dateTimeOriginal` | `bool` | Show the date the photo was taken (per EXIF). | -| `timeZone` | `bool` | Show and use the photo's timezone when formatting the date. Only applies when `dateTimeOriginal` is also enabled. | +| `dateTimeOriginal` | `bool` | Show the date the photo was taken (per EXIF), in the photographer's local time - matching Immich's own sidebar. | +| `timezone` | `bool` | Show and use the photo's timezone when formatting the date. Only applies when `dateTimeOriginal` is also enabled. | | `fileName` | `bool` | Show the original filename. | | `dimensions` | `bool` | Show width x height and megapixel count. | | `fileSize` | `bool` | Show the file size. | @@ -95,7 +95,7 @@ Show the description in the sidebar only (not as a lightbox caption), expose cam "description": { "caption": false, "sidebar": true }, "exif": { "dateTimeOriginal": true, - "timeZone": true, + "timezone": true, "make": true, "model": true, "lensModel": true, diff --git a/docs/installation.md b/docs/installation.md index 38c37a1..7eb039b 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,5 +1,8 @@ # Installation +> [!NOTE] +> IPP requires **Immich 2.0.0 or newer**. It checks the server version at startup and will exit with an error against an older Immich. + ## Install with Docker / Podman 1. Download the [docker-compose.yml](https://github.com/alangrainger/immich-public-proxy/blob/main/docker-compose.yml)