// @ts-check
// ============================================================================
// Gallery client - virtualized justified/square grid, PhotoSwipe v5 lightbox
//
// Layout is pre-computed for all items based on container width. Only tiles
// within viewport ± 1 viewport-height buffer exist in the DOM at any moment.
// PhotoSwipe runs with a full dataSource array so the lightbox navigates
// across all items regardless of which tiles are currently rendered.
// ============================================================================
// Runtime URLs served by Express, not filesystem paths. TypeScript's resolver
// can't follow them, so we silence its module-not-found errors here. The
// imports themselves work fine at runtime.
// @ts-ignore
import PhotoSwipeLightbox from '/share/static/photoswipe/photoswipe-lightbox.esm.js'
// @ts-ignore
import { thumbHashToDataURL } from '/share/static/thumbhash/thumbhash.js'
/**
* @typedef {Object} GalleryItem
* @property {string} id
* @property {'IMAGE'|'VIDEO'} type
* @property {string} previewUrl
* @property {string} thumbnailUrl
* @property {string} [downloadUrl]
* @property {string} [videoData] JSON-stringified video source info
* @property {string} [description] Escaped HTML fragment for the lightbox caption
* @property {string} downloadFilename
* @property {number} [width]
* @property {number} [height]
* @property {string} [thumbhash]
* @property {string} [fileCreatedAt] ISO date
*/
/**
* @typedef {Object} LightboxConfig
* @property {boolean} [showArrows]
* @property {boolean} [showDownload]
* @property {boolean} [mobileArrows]
*/
/**
* @typedef {Object} InitParams
* @property {GalleryItem[]} [items]
* @property {number} [openItem] 1-based; opens lightbox on the Nth item
* @property {LightboxConfig} [lightboxConfig]
* @property {boolean} [groupByDate]
*/
/**
* @typedef {Object} LayoutEntry
* @property {number} index
* @property {number} left
* @property {number} top
* @property {number} width
* @property {number} height
*/
/**
* @typedef {Object} HeaderEntry
* @property {string} label
* @property {number} top
* @property {number} height
*/
/**
* @typedef {Object} GroupSpec
* @property {string | null} label
* @property {number[]} indices
*/
// Justified-rows target row height (matches Immich's main view)
const TARGET_ROW_HEIGHT = 235
const GAP = 4
const MOBILE_BREAKPOINT = 640
const MOBILE_COLS = 3
const IMAGE_LOAD_MARGIN_PX = 300
const SCROLL_SETTLE_MS = 100
const BUFFER_VIEWPORTS = 1
// Height reserved for each month header (must agree with .group-header CSS)
const HEADER_HEIGHT = 48
// Vertical gap between groups
const GROUP_GAP = 16
// MDI download icon (Apache 2.0). Same icon set Immich uses for its viewer.
const ICON_DOWNLOAD = ''
// ----- module state ---------------------------------------------------------
/** @type {GalleryItem[]} */
let items = []
/** @type {LayoutEntry[]} - sparse, indexed by GalleryItem index */
let layout = []
/** @type {HeaderEntry[]} - empty when groupByDate is off */
let headers = []
let groupByDate = false
/** @type {HTMLElement | null} */
let container = null
/** @type {any} - PhotoSwipeLightbox instance; external module, leave untyped */
let lightbox = null
/** @type {LightboxConfig} */
let lightboxConfig = {}
/** @type {Map} */
const renderedTiles = new Map()
/** @type {Map} */
const renderedHeaders = new Map()
let lastContainerW = 0
// Selection mode (mode-toggle UX: hidden checkmarks until activated)
let selectMode = false
/** @type {Set} - set of asset IDs */
const selected = new Set()
/** @type {HTMLElement | null} */
let toolbarEl = null
/** @type {HTMLElement | null} */
let countEl = null
/** @type {HTMLButtonElement | null} */
let selectAllBtn = null
/** @type {HTMLButtonElement | null} */
let cancelBtn = null
/** @type {HTMLButtonElement | null} */
let downloadBtn = null
// Inline SVG for the check icon shown inside selected tiles' checkmark circle
const CHECK_SVG = ''
// Long-press threshold for entering select mode via touch/mouse
const LONG_PRESS_MS = 500
// ----- layout computation ---------------------------------------------------
function computeLayout (containerW) {
const tileLayout = new Array(items.length)
const newHeaders = []
const groups = groupByDate ? groupItemsByMonth() : [{ label: null, indices: itemIndices() }]
const isMobile = containerW < MOBILE_BREAKPOINT
let y = 0
for (let g = 0; g < groups.length; g++) {
const group = groups[g]
if (group.label) {
newHeaders.push({ label: group.label, top: y, height: HEADER_HEIGHT })
y += HEADER_HEIGHT
}
y = isMobile
? layoutSquareGroup(containerW, group.indices, y, tileLayout)
: layoutJustifiedGroup(containerW, group.indices, y, tileLayout)
if (g < groups.length - 1) y += GROUP_GAP
}
return {
layout: tileLayout,
headers: newHeaders,
totalHeight: Math.max(0, y)
}
}
function itemIndices () {
const out = new Array(items.length)
for (let i = 0; i < items.length; i++) out[i] = i
return out
}
/** @returns {GroupSpec[]} */
function groupItemsByMonth () {
// Preserve item order (already sorted desc by render.ts when grouping is on)
/** @type {Map} */
const map = new Map()
for (let i = 0; i < items.length; i++) {
const key = (items[i].fileCreatedAt || '').slice(0, 7) || 'undated'
let g = map.get(key)
if (!g) {
g = { label: monthLabel(key), indices: [] }
map.set(key, g)
}
g.indices.push(i)
}
return Array.from(map.values())
}
/** @param {string} key @returns {string} */
function monthLabel (key) {
if (key === 'undated') return 'Undated'
const parts = key.split('-')
const y = Number(parts[0])
const m = Number(parts[1])
if (!y || !m) return key
// Intl.DateTimeFormat picks up the browser's locale; UTC timeZone keeps
// the displayed month consistent with the UTC YYYY-MM bucket key.
return new Intl.DateTimeFormat(undefined, {
year: 'numeric',
month: 'long',
timeZone: 'UTC'
}).format(new Date(Date.UTC(y, m - 1, 1)))
}
/**
* @param {number} containerW
* @param {number[]} indices
* @param {number} startY
* @param {LayoutEntry[]} tileLayout
* @returns {number} The y position past the last tile (no trailing gap)
*/
function layoutSquareGroup (containerW, indices, startY, tileLayout) {
const tileSize = Math.floor((containerW - (MOBILE_COLS - 1) * GAP) / MOBILE_COLS)
let col = 0
let x = 0
let y = startY
for (const idx of indices) {
tileLayout[idx] = { index: idx, left: x, top: y, width: tileSize, height: tileSize }
col++
if (col === MOBILE_COLS) {
col = 0
x = 0
y += tileSize + GAP
} else {
x += tileSize + GAP
}
}
// If the last row was partial, advance y to past it
if (col > 0) y += tileSize
// Otherwise back off the trailing inter-row gap
else if (y > startY) y -= GAP
return y
}
function layoutJustifiedGroup (containerW, indices, startY, tileLayout) {
let rowItems = []
let aspectSum = 0
let y = startY
const applyRow = (rowItems, height, isLastRow) => {
const intHeight = Math.floor(height)
let x = 0
rowItems.forEach(({ idx, aspect }, i) => {
const isFinalInRow = i === rowItems.length - 1
const w = (!isLastRow && isFinalInRow)
? containerW - x
: Math.floor(aspect * height)
tileLayout[idx] = { index: idx, left: x, top: y, width: w, height: intHeight }
x += w + GAP
})
y += intHeight + GAP
}
for (const idx of indices) {
const item = items[idx]
const w = item.width || 1
const h = item.height || 1
const aspect = w / h
rowItems.push({ idx, aspect })
aspectSum += aspect
const projectedH = (containerW - (rowItems.length - 1) * GAP) / aspectSum
if (projectedH <= TARGET_ROW_HEIGHT) {
applyRow(rowItems, projectedH, false)
rowItems = []
aspectSum = 0
}
}
if (rowItems.length) applyRow(rowItems, TARGET_ROW_HEIGHT, true)
// y advanced past the last row's trailing gap; back off
return y > startY ? y - GAP : y
}
// ----- tile DOM construction ------------------------------------------------
function onThumbError () {
this.closest('a').classList.add('thumb-error')
}
// Cache of decoded thumbhash → PNG data URL. Same thumbhash on multiple
// tile-creations (revisits during virtualization) reuses the same URL.
const thumbhashCache = new Map()
function decodeThumbhash (base64) {
const cached = thumbhashCache.get(base64)
if (cached) return cached
try {
const binary = atob(base64)
const bytes = new Uint8Array(binary.length)
for (let i = 0; i < bytes.length; i++) bytes[i] = binary.charCodeAt(i)
const url = thumbHashToDataURL(bytes)
thumbhashCache.set(base64, url)
return url
} catch (e) {
return null
}
}
function createTile (index) {
const item = items[index]
const l = layout[index]
const a = document.createElement('a')
a.dataset.index = index
if (item.type !== 'VIDEO') a.href = item.previewUrl
a.style.left = l.left + 'px'
a.style.top = l.top + 'px'
a.style.width = l.width + 'px'
a.style.height = l.height + 'px'
if (item.thumbhash) {
const url = decodeThumbhash(item.thumbhash)
if (url) a.style.backgroundImage = 'url(' + url + ')'
}
const img = document.createElement('img')
// alt left empty: browsers paint alt text over the thumbhash background
// while the thumbnail downloads. Description (if any) is shown in the
// lightbox caption instead.
img.alt = ''
img.dataset.src = item.thumbnailUrl
img.onerror = onThumbError
a.appendChild(img)
if (item.type === 'VIDEO') {
const playIcon = document.createElement('div')
playIcon.className = 'play-icon'
a.appendChild(playIcon)
}
// Selection checkmark (rendered only when select mode is even possible -
// i.e. when the page included the toolbar element)
if (toolbarEl) {
const check = document.createElement('div')
check.className = 'tile-check'
check.innerHTML = CHECK_SVG
check.addEventListener('click', (e) => {
e.preventDefault()
e.stopPropagation()
if (!selectMode) enterSelectMode()
toggleSelection(item.id)
})
a.appendChild(check)
if (selected.has(item.id)) a.classList.add('selected')
attachLongPress(a, item.id)
}
a.addEventListener('click', (e) => {
e.preventDefault()
if (selectMode) {
toggleSelection(item.id)
} else {
openLightbox(index)
}
})
return a
}
// ----- long-press (enter select mode) --------------------------------------
function attachLongPress (tile, id) {
let timer = null
let pressed = false
const cancel = () => {
if (timer) { clearTimeout(timer); timer = null }
}
tile.addEventListener('pointerdown', (e) => {
// Ignore right/middle clicks
if (e.button !== undefined && e.button !== 0) return
pressed = false
timer = setTimeout(() => {
timer = null
pressed = true
if (!selectMode) enterSelectMode()
toggleSelection(id)
}, LONG_PRESS_MS)
})
tile.addEventListener('pointerup', cancel)
tile.addEventListener('pointercancel', cancel)
tile.addEventListener('pointerleave', cancel)
tile.addEventListener('pointermove', (e) => {
// Cancel long-press if pointer moves significantly (scroll, drag)
if (Math.abs(e.movementX) + Math.abs(e.movementY) > 6) cancel()
})
// Swallow the synthetic click that follows a successful long-press so it
// doesn't open the lightbox.
tile.addEventListener('click', (e) => {
if (pressed) {
pressed = false
e.preventDefault()
e.stopImmediatePropagation()
}
}, true)
}
// ----- selection state -----------------------------------------------------
function enterSelectMode () {
if (selectMode) return
selectMode = true
if (container) container.classList.add('select-mode')
if (toolbarEl) toolbarEl.hidden = false
}
function exitSelectMode () {
if (!selectMode) return
selectMode = false
// Clear DOM markers on the tiles currently in the DOM
for (const a of renderedTiles.values()) a.classList.remove('selected')
selected.clear()
if (container) container.classList.remove('select-mode')
if (toolbarEl) toolbarEl.hidden = true
updateSelectionUI()
}
function toggleSelection (id) {
if (selected.has(id)) selected.delete(id)
else selected.add(id)
const idx = items.findIndex(it => it.id === id)
const tile = idx >= 0 ? renderedTiles.get(idx) : null
if (tile) tile.classList.toggle('selected', selected.has(id))
// Auto-exit if user deselected the last item
if (selected.size === 0 && selectMode) exitSelectMode()
else updateSelectionUI()
}
function updateSelectionUI () {
if (countEl) {
countEl.textContent = selected.size + ' selected'
}
if (downloadBtn) downloadBtn.disabled = selected.size === 0
if (selectAllBtn) {
selectAllBtn.textContent =
selected.size === items.length ? 'Deselect all' : 'Select all'
}
}
function selectAllOrNone () {
if (selected.size === items.length) {
// Deselect all but keep select mode active
for (const a of renderedTiles.values()) a.classList.remove('selected')
selected.clear()
updateSelectionUI()
} else {
if (!selectMode) enterSelectMode()
for (const item of items) selected.add(item.id)
for (const a of renderedTiles.values()) a.classList.add('selected')
updateSelectionUI()
}
}
function downloadSelected () {
if (selected.size === 0) return
// Single selection: download the file directly so the user gets the image
// (or video) instead of a one-entry zip.
if (selected.size === 1) {
const id = selected.values().next().value
const item = items.find(it => it.id === id)
if (item && item.downloadUrl) {
const a = document.createElement('a')
a.href = item.downloadUrl
a.download = item.downloadFilename || ''
document.body.appendChild(a)
a.click()
a.remove()
return
}
}
// Form POST so the browser handles streaming the zip directly to disk.
const form = document.createElement('form')
form.method = 'POST'
form.action = window.location.pathname + '/download'
const input = document.createElement('input')
input.type = 'hidden'
input.name = 'assets'
input.value = JSON.stringify(Array.from(selected))
form.appendChild(input)
document.body.appendChild(form)
form.submit()
form.remove()
}
function setupToolbar () {
toolbarEl = document.getElementById('select-toolbar')
// No toolbar means downloads aren't allowed for this share; nothing to wire
if (!toolbarEl) return
countEl = document.getElementById('select-count')
selectAllBtn = /** @type {HTMLButtonElement | null} */ (document.getElementById('select-all'))
cancelBtn = /** @type {HTMLButtonElement | null} */ (document.getElementById('select-cancel'))
downloadBtn = /** @type {HTMLButtonElement | null} */ (document.getElementById('select-download'))
if (cancelBtn) cancelBtn.addEventListener('click', exitSelectMode)
if (selectAllBtn) selectAllBtn.addEventListener('click', selectAllOrNone)
if (downloadBtn) downloadBtn.addEventListener('click', downloadSelected)
updateSelectionUI()
}
// ----- virtualization -------------------------------------------------------
function getVisibleRange () {
const containerTop = container.getBoundingClientRect().top
const viewportTopInContainer = -containerTop
const viewportBottomInContainer = viewportTopInContainer + window.innerHeight
const buffer = window.innerHeight * BUFFER_VIEWPORTS
return {
top: viewportTopInContainer - buffer,
bottom: viewportBottomInContainer + buffer
}
}
function createHeader (header) {
const el = document.createElement('h2')
el.className = 'group-header'
el.style.top = header.top + 'px'
el.textContent = header.label
return el
}
function virtualize () {
if (!container || !layout.length) return
const { top, bottom } = getVisibleRange()
// Tiles
const neededTiles = new Set()
for (const l of layout) {
if (!l) continue
if (l.top + l.height < top) continue
if (l.top > bottom) break
neededTiles.add(l.index)
}
for (const [index, el] of renderedTiles) {
if (!neededTiles.has(index)) {
el.remove()
renderedTiles.delete(index)
}
}
for (const index of neededTiles) {
if (renderedTiles.has(index)) continue
const tile = createTile(index)
container.appendChild(tile)
renderedTiles.set(index, tile)
}
// Group headers (when grouping is enabled; headers is empty otherwise)
const neededHeaders = new Set()
for (const h of headers) {
if (h.top + h.height < top) continue
if (h.top > bottom) break
neededHeaders.add(h.label)
}
for (const [label, el] of renderedHeaders) {
if (!neededHeaders.has(label)) {
el.remove()
renderedHeaders.delete(label)
}
}
for (const label of neededHeaders) {
if (renderedHeaders.has(label)) continue
const h = headers.find(x => x.label === label)
if (!h) continue
const el = createHeader(h)
container.appendChild(el)
renderedHeaders.set(label, el)
}
}
function computeLayoutAndRender () {
if (!container) return
const containerW = container.clientWidth
if (containerW <= 0) return
if (containerW === lastContainerW) {
virtualize()
return
}
lastContainerW = containerW
const result = computeLayout(containerW)
layout = result.layout
headers = result.headers
container.style.height = result.totalHeight + 'px'
for (const [, el] of renderedTiles) el.remove()
renderedTiles.clear()
for (const [, el] of renderedHeaders) el.remove()
renderedHeaders.clear()
virtualize()
loadVisibleTiles()
}
// ----- image src lifecycle --------------------------------------------------
function loadVisibleTiles () {
if (!container) return
const vpHeight = window.innerHeight
const containerTop = container.getBoundingClientRect().top
for (const a of renderedTiles.values()) {
const img = a.firstElementChild
if (!(img instanceof HTMLImageElement)) continue
const aTopInVp = containerTop + parseFloat(a.style.top || '0')
const aHeight = parseFloat(a.style.height || '0')
const isFar = aTopInVp + aHeight < -IMAGE_LOAD_MARGIN_PX ||
aTopInVp > vpHeight + IMAGE_LOAD_MARGIN_PX
if (isFar) {
if (img.src && !img.complete) {
img.dataset.src = img.src
img.removeAttribute('src')
}
} else if (img.dataset.src) {
img.src = img.dataset.src
img.removeAttribute('data-src')
}
}
}
// ----- scroll handling ------------------------------------------------------
let scrollFrame = null
let loadTimer = null
function onScroll () {
if (scrollFrame == null) {
scrollFrame = requestAnimationFrame(() => {
scrollFrame = null
virtualize()
})
}
if (loadTimer) clearTimeout(loadTimer)
loadTimer = setTimeout(() => {
loadTimer = null
loadVisibleTiles()
}, SCROLL_SETTLE_MS)
}
// ----- PhotoSwipe -----------------------------------------------------------
function parseVideoData (item) {
try {
const data = JSON.parse(item.videoData || '{}')
const source = (data.source && data.source[0]) || {}
return { src: source.src || '', type: source.type || 'video/mp4' }
} catch (e) {
return { src: '', type: 'video/mp4' }
}
}
function escapeAttr (s) {
return String(s).replace(/&/g, '&').replace(/"/g, '"').replace(//g, '>')
}
function buildDataSource () {
return items.map(item => {
if (item.type === 'VIDEO') {
const v = parseVideoData(item)
return {
html:
'' +
'' +
'
'
}
}
return {
src: item.previewUrl,
width: item.width || 1600,
height: item.height || 1200,
msrc: item.thumbnailUrl,
alt: item.description || ''
}
})
}
function initLightbox () {
lightbox = new PhotoSwipeLightbox({
dataSource: buildDataSource(),
pswpModule: () => import('/share/static/photoswipe/photoswipe.esm.js'),
bgOpacity: 1,
showHideAnimationType: 'fade',
closeOnVerticalDrag: true,
arrowKeys: true,
loop: false,
padding: { top: 56, bottom: 56, left: 16, right: 16 }
})
// Download button (only registered if config enables it)
if (lightboxConfig.showDownload) {
lightbox.on('uiRegister', () => {
lightbox.pswp.ui.registerElement({
name: 'download-button',
order: 8,
isButton: true,
tagName: 'a',
ariaLabel: 'Download',
html: ICON_DOWNLOAD,
onInit: (el, pswp) => {
el.setAttribute('target', '_blank')
el.setAttribute('rel', 'noopener')
const update = () => {
const item = items[pswp.currIndex]
if (item && item.downloadUrl) {
el.href = item.downloadUrl
el.setAttribute('download', item.downloadFilename || '')
} else {
el.removeAttribute('href')
}
}
update()
pswp.on('change', update)
}
})
})
}
// Caption from EXIF description (only present when item.description is set;
// server-side gated on ipp.showMetadata.description). Content is already
// HTML-escaped in render.ts, so innerHTML assignment is safe.
lightbox.on('uiRegister', () => {
lightbox.pswp.ui.registerElement({
name: 'caption',
order: 9,
isButton: false,
appendTo: 'root',
onInit: (el, pswp) => {
el.classList.add('pswp__caption')
const render = () => {
const item = items[pswp.currIndex]
const text = (item && item.description) || ''
el.innerHTML = text
el.hidden = !text
}
render()
pswp.on('change', render)
}
})
})
// Hash navigation: sync window.location.hash with the open slide
lightbox.on('uiRegister', () => {
const pswp = lightbox.pswp
pswp.on('change', () => {
const item = items[pswp.currIndex]
if (item) history.replaceState(null, '', '#' + item.id)
})
pswp.on('close', () => {
history.replaceState(null, '', window.location.pathname + window.location.search)
scrollToCurrentSlide(pswp.currIndex)
})
})
// Optional control hiding (defaults match Immich's behavior)
const docEl = document.documentElement
if (!lightboxConfig.showArrows) docEl.classList.add('pswp-no-arrows')
if (!lightboxConfig.mobileArrows) docEl.classList.add('pswp-no-mobile-arrows')
lightbox.init()
}
function openLightbox (index) {
if (lightbox) lightbox.loadAndOpen(index)
}
/**
* Scroll the page so the tile for the given item is comfortably in view.
* Called from the lightbox close handler - if the user navigated prev/next
* inside the lightbox, or arrived via a #asset-id deep link, the tile they
* end on may be far from the original scroll position. We only scroll when
* the tile is genuinely off-screen, so closing on a still-visible tile
* doesn't jiggle the page.
*/
function scrollToCurrentSlide (index) {
if (!container || index == null || !layout[index]) return
const entry = layout[index]
const containerTop = container.getBoundingClientRect().top + window.scrollY
const tileTop = containerTop + entry.top
const tileBottom = tileTop + entry.height
const viewportTop = window.scrollY
const viewportBottom = viewportTop + window.innerHeight
// Already mostly visible - leave the scroll alone
if (tileTop >= viewportTop && tileBottom <= viewportBottom) return
// Center the tile vertically in the viewport
const targetScroll = tileTop - (window.innerHeight - entry.height) / 2
window.scrollTo({ top: Math.max(0, targetScroll), behavior: 'instant' })
}
// ----- entry point ----------------------------------------------------------
function readInitParams () {
const el = document.getElementById('ipp-init')
if (!el) return {}
try { return JSON.parse(el.textContent || '{}') } catch (e) { return {} }
}
function init () {
const params = readInitParams()
items = params.items || []
lightboxConfig = params.lightboxConfig || {}
groupByDate = !!params.groupByDate
container = document.getElementById('gallery')
if (!container) return
setupToolbar()
initLightbox()
let resizeFrame
const resizeObserver = new ResizeObserver(() => {
if (resizeFrame) cancelAnimationFrame(resizeFrame)
resizeFrame = requestAnimationFrame(computeLayoutAndRender)
})
resizeObserver.observe(container)
window.addEventListener('scroll', onScroll, { passive: true })
// Deep-link: prefer #asset-id in the URL hash, fall back to ?openItem
const hash = window.location.hash.slice(1)
if (hash) {
const idx = items.findIndex(it => it.id === hash)
if (idx >= 0) openLightbox(idx)
} else if (params.openItem && params.openItem > 0 && params.openItem <= items.length) {
openLightbox(params.openItem - 1)
}
}
init()