@hearthlog/module-gallery 0.0.0-stage → 1.0.0

package/src/gallery/format.ts

@@ -0,0 +1,101 @@
+import { format } from 'date-fns';
+import { formatNumber } from '@hearthlog/sdk/format';
+import { formatFileSize } from '@hearthlog/sdk/format';
+
+export interface PhotoDetailSource {
+    captured_at: string;
+    timeline_day: string;
+    camera_make: string;
+    camera_model: string;
+    lens_model: string;
+    focal_length: number;
+    f_number: number;
+    exposure_time: number;
+    iso: number;
+    latitude: number | null;
+    longitude: number | null;
+    width: number;
+    height: number;
+    byte_size: number;
+}
+
+/** Capture time in the camera's own wall-clock time; the import day without one. */
+export function formatPhotoDate(photo: Pick<PhotoDetailSource, 'captured_at' | 'timeline_day'>): string {
+    const match = /^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2}))?/.exec(photo.captured_at || photo.timeline_day);
+    if (!match) return '';
+    const [, year, month, day, hour, minute] = match;
+    const date = new Date(Number(year), Number(month) - 1, Number(day), Number(hour ?? 0), Number(minute ?? 0));
+    return hour === undefined ? format(date, 'd MMMM yyyy') : format(date, 'd MMMM yyyy, HH:mm');
+}
+
+export function formatCamera(photo: Pick<PhotoDetailSource, 'camera_make' | 'camera_model'>): string {
+    return [photo.camera_make, photo.camera_model].filter(Boolean).join(' ');
+}
+
+/** `ƒ/1.8 · 1/120 s · ISO 50 · 26 mm` from whichever values the camera recorded. */
+export function formatExposure(photo: Pick<PhotoDetailSource, 'f_number' | 'exposure_time' | 'iso' | 'focal_length'>): string {
+    const parts: string[] = [];
+    if (photo.f_number > 0) parts.push(`ƒ/${formatNumber(photo.f_number, 1)}`);
+    if (photo.exposure_time > 0) {
+        parts.push(photo.exposure_time >= 1
+            ? `${formatNumber(photo.exposure_time, 1)} s`
+            : `1/${Math.round(1 / photo.exposure_time)} s`);
+    }
+    if (photo.iso > 0) parts.push(`ISO ${photo.iso}`);
+    if (photo.focal_length > 0) parts.push(`${formatNumber(photo.focal_length, 1)} mm`);
+    return parts.join(' · ');
+}
+
+export function formatPhotoFile(photo: Pick<PhotoDetailSource, 'width' | 'height' | 'byte_size'>): string {
+    const dimensions = photo.width > 0 && photo.height > 0 ? `${photo.width} × ${photo.height}` : '';
+    return [dimensions, photo.byte_size > 0 ? formatFileSize(photo.byte_size) : ''].filter(Boolean).join(' · ');
+}
+
+export function formatCoordinates(photo: Pick<PhotoDetailSource, 'latitude' | 'longitude'>): string {
+    if (photo.latitude === null || photo.longitude === null) return '';
+    const latitude = `${Math.abs(photo.latitude).toFixed(4)}° ${photo.latitude < 0 ? 'S' : 'N'}`;
+    const longitude = `${Math.abs(photo.longitude).toFixed(4)}° ${photo.longitude < 0 ? 'W' : 'E'}`;
+    return `${latitude}, ${longitude}`;
+}
+
+export function mapHref(photo: Pick<PhotoDetailSource, 'latitude' | 'longitude'>): string {
+    if (photo.latitude === null || photo.longitude === null) return '';
+    return `https://www.openstreetmap.org/?mlat=${photo.latitude}&mlon=${photo.longitude}#map=15/${photo.latitude}/${photo.longitude}`;
+}
+
+export interface PhotoDetailRow {
+    label: string;
+    value: string;
+    /** A link that opens the value elsewhere, such as a map. */
+    href?: string;
+}
+
+/** The camera, exposure, file, and location lines the viewer lists, leaving out any it lacks. */
+export function photoDetailRows(photo: PhotoDetailSource, options: { file?: boolean } = {}): PhotoDetailRow[] {
+    const rows: PhotoDetailRow[] = [];
+    const camera = [formatCamera(photo), photo.lens_model].filter(Boolean).join(' · ');
+    if (camera) rows.push({ label: 'Camera', value: camera });
+    const exposure = formatExposure(photo);
+    if (exposure) rows.push({ label: 'Exposure', value: exposure });
+    if (options.file ?? true) {
+        const file = formatPhotoFile(photo);
+        if (file) rows.push({ label: 'File', value: file });
+    }
+    const location = formatCoordinates(photo);
+    if (location) rows.push({ label: 'Location', value: location, href: mapHref(photo) });
+    return rows;
+}
+
+/** `June` and `2024` for a `2024-06` month. */
+export function formatMonthParts(month: string): { name: string; year: string } {
+    return { name: format(new Date(Number(month.slice(0, 4)), Number(month.slice(5, 7)) - 1, 1), 'MMMM'), year: month.slice(0, 4) };
+}
+
+export function formatPhotoCount(count: number): string {
+    return `${formatNumber(count)} ${count === 1 ? 'photo' : 'photos'}`;
+}
+
+/** `Sat 14 Jun` for a `yyyy-MM-dd` day. */
+export function formatTileDay(day: string): string {
+    return format(new Date(`${day.slice(0, 10)}T12:00:00`), 'EEE d MMM');
+}

package/src/gallery/interaction.ts

@@ -0,0 +1,6 @@
+export function gallerySwipeDirection(startX: number, startY: number, endX: number, endY: number): -1 | 0 | 1 {
+    const horizontal = endX - startX;
+    const vertical = endY - startY;
+    if (Math.abs(horizontal) < 60 || Math.abs(horizontal) < Math.abs(vertical) * 1.5) return 0;
+    return horizontal < 0 ? 1 : -1;
+}

package/src/gallery/layout.ts

@@ -0,0 +1,67 @@
+/** Tiles keep a photo's shape between these ratios; wider panoramas and taller shots are cropped to them. */
+export const MIN_TILE_RATIO = 0.5;
+export const MAX_TILE_RATIO = 3;
+
+/** Width over height as a tile shows it; a photo without dimensions is square. */
+export function tileRatio(photo: { width: number; height: number }): number {
+    return photo.width > 0 && photo.height > 0
+        ? Math.min(MAX_TILE_RATIO, Math.max(MIN_TILE_RATIO, photo.width / photo.height))
+        : 1;
+}
+
+export interface GalleryRow {
+    /** The first photo in the row. */
+    start: number;
+    /** One past the last photo in the row. */
+    end: number;
+    height: number;
+}
+
+/** The most photos one row holds. */
+const ROW_LIMIT = 12;
+
+/**
+ * Presentation geometry for photos SQL already ordered: rows that fill the
+ * width exactly. The breaks are chosen for the whole block at once, so every
+ * row stays close to the target height; a short last row keeps the target
+ * height instead of stretching.
+ */
+export function justifiedRows(ratios: readonly number[], width: number, target: number, gap: number): GalleryRow[] {
+    const count = ratios.length;
+    if (count === 0 || width <= 0 || target <= 0) return [];
+    const cost = new Float64Array(count + 1).fill(Infinity);
+    const previous = new Int32Array(count + 1);
+    cost[0] = 0;
+    for (let end = 1; end <= count; end++) {
+        let sum = 0;
+        for (let start = end - 1; start >= 0 && end - start <= ROW_LIMIT; start--) {
+            sum += ratios[start];
+            const size = end - start;
+            const height = (width - gap * (size - 1)) / sum;
+            if (height < target * 0.55 && size > 1) break;
+            let penalty: number;
+            if (end === count && height >= target) penalty = 0;
+            else if (height > target * 1.9) continue;
+            else penalty = ((height - target) / target) ** 2 * (height > target ? 1.6 : 1);
+            if (cost[start] + penalty < cost[end]) {
+                cost[end] = cost[start] + penalty;
+                previous[end] = start;
+            }
+        }
+        // A photo no row can hold at a sensible height stands alone.
+        if (cost[end] === Infinity) {
+            cost[end] = cost[end - 1] + 10;
+            previous[end] = end - 1;
+        }
+    }
+    const rows: GalleryRow[] = [];
+    for (let end = count; end > 0;) {
+        const start = previous[end];
+        let sum = 0;
+        for (let index = start; index < end; index++) sum += ratios[index];
+        const height = (width - gap * (end - start - 1)) / sum;
+        rows.push({ start, end, height: Math.min(end === count ? target : target * 2, height) });
+        end = start;
+    }
+    return rows.reverse();
+}

package/src/gallery/public-details.ts

@@ -0,0 +1,73 @@
+import type { PublicGalleryPhotoDetails } from '../../public/contract.js';
+import { formatCamera, type PhotoDetailSource } from './format.js';
+
+/** What a published gallery shows about each photo; every switch starts on. */
+export interface PublicDetailSwitches {
+    camera: boolean;
+    date: boolean;
+    location: boolean;
+}
+
+export const SHARE_ALL_DETAILS: PublicDetailSwitches = { camera: true, date: true, location: true };
+
+type PrivateDetails = Pick<PhotoDetailSource,
+    'captured_at' | 'timeline_day' | 'camera_make' | 'camera_model' | 'lens_model'
+    | 'f_number' | 'exposure_time' | 'iso' | 'focal_length' | 'latitude' | 'longitude'>;
+
+const CAPTURED = /^(\d{4}-\d{2}-\d{2})(?:T(\d{2}:\d{2}))?/;
+
+/**
+ * The details a photo publishes under the owner's switches. The date is the
+ * camera's capture time, or the day the photo sits on the private timeline.
+ */
+export function publicPhotoDetails(photo: PrivateDetails, switches: PublicDetailSwitches): PublicGalleryPhotoDetails {
+    const details: PublicGalleryPhotoDetails = {};
+    if (switches.date) {
+        const captured = CAPTURED.exec(photo.captured_at || '');
+        const takenAt = captured ? (captured[2] ? `${captured[1]}T${captured[2]}` : captured[1]) : CAPTURED.exec(photo.timeline_day)?.[1];
+        if (takenAt) details.takenAt = takenAt;
+    }
+    if (switches.camera) {
+        const camera = formatCamera(photo).slice(0, 120);
+        if (camera) details.camera = camera;
+        if (photo.lens_model) details.lens = photo.lens_model.slice(0, 120);
+        if (photo.f_number > 0) details.fNumber = photo.f_number;
+        if (photo.exposure_time > 0) details.exposureTime = photo.exposure_time;
+        if (photo.iso > 0) details.iso = photo.iso;
+        if (photo.focal_length > 0) details.focalLength = photo.focal_length;
+    }
+    if (switches.location && photo.latitude !== null && photo.longitude !== null) {
+        details.latitude = photo.latitude;
+        details.longitude = photo.longitude;
+    }
+    return details;
+}
+
+/** The switches an earlier review used, read from what its photos published. */
+export function detailSwitchesFrom(photos: readonly PublicGalleryPhotoDetails[]): PublicDetailSwitches {
+    return {
+        camera: photos.some((photo) => photo.camera || photo.lens || photo.fNumber || photo.exposureTime || photo.iso || photo.focalLength),
+        date: photos.some((photo) => photo.takenAt),
+        location: photos.some((photo) => photo.latitude !== undefined),
+    };
+}
+
+/** Published details in the shape the shared formatters read. */
+export function publicDetailSource(photo: PublicGalleryPhotoDetails & { width: number; height: number }): PhotoDetailSource {
+    return {
+        captured_at: photo.takenAt?.includes('T') ? photo.takenAt : '',
+        timeline_day: photo.takenAt?.slice(0, 10) ?? '',
+        camera_make: '',
+        camera_model: photo.camera ?? '',
+        lens_model: photo.lens ?? '',
+        focal_length: photo.focalLength ?? 0,
+        f_number: photo.fNumber ?? 0,
+        exposure_time: photo.exposureTime ?? 0,
+        iso: photo.iso ?? 0,
+        latitude: photo.latitude ?? null,
+        longitude: photo.longitude ?? null,
+        width: photo.width,
+        height: photo.height,
+        byte_size: 0,
+    };
+}

package/src/gallery/publication-api.ts

@@ -0,0 +1,68 @@
+import { fetchAccessProtected } from '@hearthlog/sdk/runtime';
+import type { PublicGalleryPhotoDetails } from '../../public/contract.js';
+
+/** A photo as reviewed, with the details the owner kept switched on. */
+export interface PublicationReviewPhoto extends PublicGalleryPhotoDetails {
+    photoId: string;
+    fileVersionId: string;
+    caption: string;
+    alt: string;
+    width: number;
+    height: number;
+}
+
+export interface PublicationReview {
+    title: string;
+    description: string;
+    photos: PublicationReviewPhoto[];
+}
+
+export interface PublicationStatus {
+    publicationId: string;
+    activeRevision: string | null;
+    publicUrl: string;
+    cleanupRevisions?: string[];
+}
+
+function endpoint(logId: string, publicationId: string): string {
+    return `/api/gallery-publications/v1/logs/${encodeURIComponent(logId)}/publications/${encodeURIComponent(publicationId)}`;
+}
+
+async function request<T>(url: string, init: RequestInit = {}): Promise<T> {
+    const response = await fetchAccessProtected(url, init);
+    const value = await response.json().catch(() => null) as { error?: string } | null;
+    if (!response.ok) throw new Error(value?.error ?? 'The public gallery request failed.');
+    if (!value || typeof value !== 'object') throw new Error('The public gallery response was unavailable.');
+    return value as T;
+}
+
+export function publicationStatus(logId: string, publicationId: string): Promise<PublicationStatus> {
+    return request(endpoint(logId, publicationId));
+}
+
+export function publicationRevision(logId: string, publicationId: string, revision: string): Promise<PublicationReview> {
+    return request(`${endpoint(logId, publicationId)}/revisions/${encodeURIComponent(revision)}`);
+}
+
+export async function publishGallery(
+    logId: string, publicationId: string, revision: string, review: PublicationReview,
+    onProgress?: (completed: number, total: number) => void,
+): Promise<PublicationStatus> {
+    const base = `${endpoint(logId, publicationId)}/revisions/${encodeURIComponent(revision)}`;
+    const staged = await request<{ chunks: number }>(base, {
+        method: 'PUT', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(review),
+    });
+    for (let chunk = 0; chunk < staged.chunks; chunk += 1) {
+        await request(`${base}/chunks/${chunk}`, { method: 'POST' });
+        onProgress?.(chunk + 1, staged.chunks);
+    }
+    return request(`${base}/activate`, { method: 'POST' });
+}
+
+export function unpublishGallery(logId: string, publicationId: string): Promise<PublicationStatus> {
+    return request(`${endpoint(logId, publicationId)}/unpublish`, { method: 'POST' });
+}
+
+export function cleanupPublicRevision(logId: string, publicationId: string, revision: string): Promise<{ remaining: boolean; deleted: number }> {
+    return request(`${endpoint(logId, publicationId)}/revisions/${encodeURIComponent(revision)}/cleanup`, { method: 'POST' });
+}

package/src/gallery/selection.ts

@@ -0,0 +1,25 @@
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export function gallerySelectionToken(searchParams: URLSearchParams): string {
+    const token = searchParams.get('selection') ?? '';
+    return UUID.test(token) ? token : '';
+}
+
+function key(tenantId: string, logId: string, token: string): string {
+    return `stor:gallery-selection:${tenantId}:${logId}:${token}`;
+}
+
+export function readGallerySelection(storage: Storage, tenantId: string, logId: string, token: string): Set<string> {
+    if (!UUID.test(token) || !tenantId || !logId) return new Set();
+    try {
+        const value: unknown = JSON.parse(storage.getItem(key(tenantId, logId, token)) ?? '[]');
+        if (!Array.isArray(value) || value.length > 10_000 || value.some((id) => typeof id !== 'string' || !UUID.test(id))) return new Set();
+        return new Set(value);
+    } catch { return new Set(); }
+}
+
+export function writeGallerySelection(storage: Storage, tenantId: string, logId: string, token: string, photoIds: Set<string>): void {
+    if (!UUID.test(token) || !tenantId || !logId || photoIds.size > 10_000) return;
+    try { storage.setItem(key(tenantId, logId, token), JSON.stringify([...photoIds])); }
+    catch { /* Selection remains usable in this tab when storage is unavailable. */ }
+}

package/src/gallery/timeline.ts

@@ -0,0 +1,77 @@
+/**
+ * The gallery timeline lists blocks of photos in time order. A block is a
+ * month, and a big month splits into parts of `GALLERY_BLOCK_SIZE` photos so
+ * the endless list only keeps what is on screen. Keys sort in time order:
+ * `2024-06/000`, `2024-06/001`, `2024-07/000`.
+ */
+export const GALLERY_BLOCK_SIZE = 240;
+
+export function galleryBlockKey(month: string, part = 0): string {
+    return `${month}/${String(part).padStart(3, '0')}`;
+}
+
+export function galleryBlockMonth(key: string): string {
+    return key.slice(0, 7);
+}
+
+export function galleryBlockPart(key: string): number {
+    return Number(key.slice(8)) || 0;
+}
+
+/**
+ * Orders block keys the way the timeline lists them: newest month first, and
+ * within a month the newest part (part 0) first.
+ */
+export function compareGalleryBlockKeys(left: string, right: string): number {
+    const leftMonth = left.slice(0, 7);
+    const rightMonth = right.slice(0, 7);
+    if (leftMonth !== rightMonth) return leftMonth < rightMonth ? 1 : -1;
+    return galleryBlockPart(left) - galleryBlockPart(right);
+}
+
+/** Photo size, from small to large; each device keeps its own. */
+export type GalleryDensity = 0 | 1 | 2;
+export const GALLERY_DENSITY_KEY = 'gallery:density';
+
+export function parseGalleryDensity(value: unknown): GalleryDensity {
+    return value === 0 || value === 1 || value === 2 ? value : 1;
+}
+
+export interface GalleryGeometry {
+    /** The width rows fill. */
+    width: number;
+    rowHeight: number;
+    gap: number;
+    /** A month header's height. */
+    header: number;
+    /** Space after a month's last block. */
+    monthGap: number;
+}
+
+/** Rows grow with the list: phones get shorter rows and narrower gaps. */
+export function galleryGeometry(width: number, density: GalleryDensity): GalleryGeometry {
+    const wide = width >= 600;
+    return {
+        width,
+        rowHeight: (wide ? [150, 220, 310] : [96, 132, 184])[density],
+        gap: wide ? 5 : 3,
+        header: wide ? 60 : 52,
+        monthGap: wide ? 24 : 16,
+    };
+}
+
+export interface GalleryBlockShape {
+    part: number;
+    parts: number;
+    photos: number;
+    ratio_sum: number;
+}
+
+/** A block's height before it renders, from its photo count and the sum of their shapes. */
+export function estimateGalleryBlock(block: GalleryBlockShape | undefined, geometry: GalleryGeometry): number {
+    if (!block || geometry.width <= 0) return geometry.header + geometry.rowHeight;
+    const rows = (block.ratio_sum * geometry.rowHeight + block.photos * geometry.gap) / (geometry.width + geometry.gap);
+    return (block.part === 0 ? geometry.header : 0)
+        + Math.max(1, Math.round(rows + 0.4)) * (geometry.rowHeight + geometry.gap)
+        + (block.part === block.parts - 1 ? geometry.monthGap : 0);
+}