#273 refinements: match Immich date display, fix timeline UTC parsing, rename timezone flag

This commit is contained in:
Alan Grainger
2026-07-27 12:14:19 +12:00
parent 4ba5c2eeee
commit f8c83bc1f4
13 changed files with 174 additions and 59 deletions
+1 -1
View File
@@ -18,7 +18,7 @@
}, },
"exif": { "exif": {
"dateTimeOriginal": false, "dateTimeOriginal": false,
"timeZone": false, "timezone": false,
"fileName": false, "fileName": false,
"dimensions": false, "dimensions": false,
"fileSize": false, "fileSize": false,
-3
View File
@@ -523,9 +523,6 @@ html.ipp-sidebar-open .ipp-sidebar {
opacity: 0.8; opacity: 0.8;
} }
.ipp-sidebar-date {
padding: 12px 0;
}
.ipp-sidebar-date-primary { .ipp-sidebar-date-primary {
font-weight: 500; font-weight: 500;
} }
+5 -6
View File
@@ -100,12 +100,11 @@ function dateLabel (key: string, mode: GroupByDateMode): string {
if (!y || !m) return key if (!y || !m) return key
// Intl.DateTimeFormat picks up the browser's locale; UTC timeZone keeps the // Intl.DateTimeFormat picks up the browser's locale; UTC timeZone keeps the
// displayed date consistent with the bucket key (which is already local). // displayed date consistent with the bucket key (which is already local).
return new Intl.DateTimeFormat(undefined, { // Day headers use Immich's timeline format ("Sat, 18 Oct 2025").
year: 'numeric', return new Intl.DateTimeFormat(undefined, mode === 'day'
month: 'long', ? { weekday: 'short', day: 'numeric', month: 'short', year: 'numeric', timeZone: 'UTC' }
...(mode === 'day' ? { day: 'numeric' } : {}), : { month: 'long', year: 'numeric', timeZone: 'UTC' }
timeZone: 'UTC' ).format(new Date(Date.UTC(y, m - 1, mode === 'day' ? (d || 1) : 1)))
}).format(new Date(Date.UTC(y, m - 1, mode === 'day' ? (d || 1) : 1)))
} }
/** /**
+74 -33
View File
@@ -143,7 +143,7 @@ function renderContents (root: HTMLElement, item: GalleryItem | undefined) {
const exif = item.exif const exif = item.exif
if (exif && hasAnyExifField(exif)) { if (exif && hasAnyExifField(exif)) {
root.appendChild(renderSection('details', ...renderDetailRows(exif))) root.appendChild(renderSection('details', ...renderDetailRows(exif, item)))
} }
if (exif && hasAnyLocationField(exif)) { if (exif && hasAnyLocationField(exif)) {
@@ -192,7 +192,7 @@ function renderDescription (description: string): HTMLElement {
return el return el
} }
function renderDetailRows (exif: GalleryExif): HTMLElement[] { function renderDetailRows (exif: GalleryExif, item: GalleryItem): HTMLElement[] {
const heading = document.createElement('h3') const heading = document.createElement('h3')
heading.className = 'ipp-sidebar-heading' heading.className = 'ipp-sidebar-heading'
heading.textContent = 'Details' heading.textContent = 'Details'
@@ -200,7 +200,7 @@ function renderDetailRows (exif: GalleryExif): HTMLElement[] {
const rows: HTMLElement[] = [heading] const rows: HTMLElement[] = [heading]
if (exif.dateTimeOriginal) { if (exif.dateTimeOriginal) {
rows.push(renderDateRow(exif.dateTimeOriginal, exif.timeZone)) rows.push(renderDateRow(exif.dateTimeOriginal, exif.timeZone, item.localDateTime))
} }
const fileRow = renderFileRow(exif) const fileRow = renderFileRow(exif)
if (fileRow) rows.push(fileRow) if (fileRow) rows.push(fileRow)
@@ -212,11 +212,20 @@ function renderDetailRows (exif: GalleryExif): HTMLElement[] {
return rows return rows
} }
function renderDateRow (iso: string, timeZone?: string): HTMLElement { function renderDateRow (iso: string, timeZone?: string, localDateTime?: string): HTMLElement {
const row = makeRow(ICON_CALENDAR) const row = makeRow(ICON_CALENDAR)
row.classList.add('ipp-sidebar-date') row.classList.add('ipp-sidebar-date')
const body = row.querySelector('.ipp-sidebar-row-body') as HTMLElement 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') const date = document.createElement('p')
date.className = 'ipp-sidebar-date-primary' date.className = 'ipp-sidebar-date-primary'
date.textContent = formatted.date date.textContent = formatted.date
@@ -396,52 +405,84 @@ export interface FormattedDate {
time: string 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) const d = new Date(iso)
if (isNaN(d.getTime())) return { date: iso, time: '' } if (isNaN(d.getTime())) return { date: iso, time: '' }
if (timeZone) { 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 { return {
date: new Intl.DateTimeFormat(undefined, { ...DATE_FORMAT_OPTIONS, timeZone }).format(d), date: new Intl.DateTimeFormat(locales, { ...DATE_FORMAT_OPTIONS, timeZone }).format(d),
time: new Intl.DateTimeFormat(undefined, { time: new Intl.DateTimeFormat(locales, timeOptions).format(d)
...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)
}
} }
}
try { // Fixed-offset values from Immich ("UTC+8") that Intl rejects: shift the
return { // instant manually and append the offset label ourselves. Anything else
date: new Intl.DateTimeFormat(undefined, { ...DATE_FORMAT_OPTIONS, timeZone }).format(d), // unrecognised falls through to browser-local formatting.
time: new Intl.DateTimeFormat(undefined, { ...TIME_FORMAT_OPTIONS, timeZone }).format(d) const offsetMinutes = parseFixedOffset(timeZone)
} if (offsetMinutes != null) {
} catch (e) { const localWallClock = new Date(d.getTime() + offsetMinutes * 60_000)
// Invalid/unknown timezone: retain the previous browser-local fallback. 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 { try {
return { return {
date: new Intl.DateTimeFormat(undefined, DATE_FORMAT_OPTIONS).format(d), date: new Intl.DateTimeFormat(locales, DATE_FORMAT_OPTIONS).format(d),
time: new Intl.DateTimeFormat(undefined, TIME_FORMAT_OPTIONS).format(d) time: new Intl.DateTimeFormat(locales, TIME_FORMAT_OPTIONS).format(d)
} }
} catch (e) { } catch {
return { date: iso, time: '' } 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 { function parseFixedOffset (timeZone: string): number | null {
const match = /^(?:UTC|GMT)([+-])(\d{1,2})(?::?(\d{2}))?$/i.exec(timeZone.trim()) const match = /^(?:UTC|GMT)([+-])(\d{1,2})(?::?(\d{2}))?$/i.exec(timeZone.trim())
if (!match) return null if (!match) return null
+1 -1
View File
@@ -81,7 +81,7 @@ const EXIF_RULES: FieldRule[] = [
if (info.dateTimeOriginal) { if (info.dateTimeOriginal) {
out.dateTimeOriginal = info.dateTimeOriginal out.dateTimeOriginal = info.dateTimeOriginal
// Never expose the timezone independently of the opted-in date. // 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
} }
} }
}, },
+7 -2
View File
@@ -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 * 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. * 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 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 if (isNaN(ms)) return undefined
return new Date(ms + (offsetHours || 0) * 3600_000).toISOString() return new Date(ms + (offsetHours || 0) * 3600_000).toISOString()
} }
+2 -2
View File
@@ -97,7 +97,7 @@ describe('buildAssetMetadata', () => {
}) })
it('returns the photo timezone only when both date and timezone are enabled', () => { 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()) const meta = buildAssetMetadata(asset(), share())
expect(meta.exif?.dateTimeOriginal).toBe('2025-10-18T06:28:54.000Z') expect(meta.exif?.dateTimeOriginal).toBe('2025-10-18T06:28:54.000Z')
expect(meta.exif?.timeZone).toBe('Asia/Singapore') expect(meta.exif?.timeZone).toBe('Asia/Singapore')
@@ -105,7 +105,7 @@ describe('buildAssetMetadata', () => {
setConfig({ ipp: { showMetadata: { exif: { dateTimeOriginal: true } } } }) setConfig({ ipp: { showMetadata: { exif: { dateTimeOriginal: true } } } })
expect(buildAssetMetadata(asset(), share()).exif?.timeZone).toBeUndefined() 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() expect(buildAssetMetadata(asset(), share()).exif).toBeUndefined()
}) })
+46
View File
@@ -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()
})
})
+1 -1
View File
@@ -186,7 +186,7 @@ describe('metadataEnabled shim', () => {
const exif = ((config.ipp as Record<string, unknown>).showMetadata as Record<string, unknown>).exif as Record<string, unknown> const exif = ((config.ipp as Record<string, unknown>).showMetadata as Record<string, unknown>).exif as Record<string, unknown>
expect(exif.enabled).toBeUndefined() expect(exif.enabled).toBeUndefined()
expect(exif.dateTimeOriginal).toBe(true) expect(exif.dateTimeOriginal).toBe(true)
expect(exif.timeZone).toBeUndefined() expect(exif.timezone).toBeUndefined()
expect(exif.fileName).toBe(true) expect(exif.fileName).toBe(true)
expect(exif.dimensions).toBe(true) expect(exif.dimensions).toBe(true)
expect(exif.fileSize).toBe(true) expect(exif.fileSize).toBe(true)
+28 -4
View File
@@ -1,11 +1,14 @@
import { describe, expect, it } from 'vitest' 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', () => { describe('sidebar date formatting', () => {
const capturedAt = '2025-10-18T06:28:54.000Z' const capturedAt = '2025-10-18T06:28:54.000Z'
it('formats the capture instant in the photo IANA timezone', () => { 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.date).toBe('Oct 18, 2025')
expect(formatted.time).toContain('Sat') expect(formatted.time).toContain('Sat')
expect(formatted.time).toContain('2:28:54 PM') expect(formatted.time).toContain('2:28:54 PM')
@@ -13,13 +16,34 @@ describe('sidebar date formatting', () => {
}) })
it('supports legacy fixed-offset timezones from Immich', () => { 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.date).toBe('Oct 18, 2025')
expect(formatted.time).toContain('2:28:54 PM') expect(formatted.time).toContain('2:28:54 PM')
expect(formatted.time).toContain('GMT+08:00') 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', () => { 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: '' })
}) })
}) })
+1 -1
View File
@@ -73,7 +73,7 @@ Group the gallery's thumbnails by date, with a header above each group.
- `false` - no grouping (default). - `false` - no grouping (default).
- `"month"` - month headers like "December 2024". - `"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). 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).
+5 -5
View File
@@ -13,7 +13,7 @@ Show the description in the sidebar only (not as a lightbox caption), expose cam
"description": { "caption": false, "sidebar": true }, "description": { "caption": false, "sidebar": true },
"exif": { "exif": {
"dateTimeOriginal": true, "dateTimeOriginal": true,
"timeZone": true, "timezone": true,
"make": true, "make": true,
"model": true, "model": true,
"lensModel": 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 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 ## Description
@@ -59,8 +59,8 @@ Under `ipp.showMetadata.exif`. Every flag defaults to `false`.
| Option | Type | Description | | Option | Type | Description |
|--------------------|--------|------------------------------------------------------------------------------------------------------------------| |--------------------|--------|------------------------------------------------------------------------------------------------------------------|
| `dateTimeOriginal` | `bool` | Show the date the photo was taken (per EXIF). | | `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. | | `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. | | `fileName` | `bool` | Show the original filename. |
| `dimensions` | `bool` | Show width x height and megapixel count. | | `dimensions` | `bool` | Show width x height and megapixel count. |
| `fileSize` | `bool` | Show the file size. | | `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 }, "description": { "caption": false, "sidebar": true },
"exif": { "exif": {
"dateTimeOriginal": true, "dateTimeOriginal": true,
"timeZone": true, "timezone": true,
"make": true, "make": true,
"model": true, "model": true,
"lensModel": true, "lensModel": true,
+3
View File
@@ -1,5 +1,8 @@
# Installation # 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 ## Install with Docker / Podman
1. Download the [docker-compose.yml](https://github.com/alangrainger/immich-public-proxy/blob/main/docker-compose.yml) 1. Download the [docker-compose.yml](https://github.com/alangrainger/immich-public-proxy/blob/main/docker-compose.yml)