feat: keyboard navigation to timeline (#17798)

* feat: improve focus

* feat: keyboard nav

* feat: improve focus

* typo

* test

* fix test

* lint

* bad merge

* lint

* inadvertent

* lint

* fix: flappy e2e test

* bad merge and fix tests

* use modulus in loop

* tests

* react to modal dialog refactor

* regression due to deferLayout

* Review comments

* Re-use change-date instead of new component

* bad merge

* Review comments

* rework moveFocus

* lint

* Fix outline

* use Date

* Finish up removing/reducing date parsing

* lint

* title

* strings

* Rework dates, rework earlier/later algorithm

* bad merge

* fix tests

* Fix race in scroll comp

* consolidate scroll methods

* Review comments

* console.log

* Edge cases in scroll compensation

* edge case, optimizations

* review comments

* lint

* lint

* More edge cases

* lint

---------

Co-authored-by: mertalev <101130780+mertalev@users.noreply.github.com>
Co-authored-by: Alex <alex.tran1502@gmail.com>

web/src/lib/utils/asset-utils.ts

@@ -477,13 +477,13 @@ export const selectAllAssets = async (assetStore: AssetStore, assetInteraction:
 
   try {
     for (const bucket of assetStore.buckets) {
-      await assetStore.loadBucket(bucket.bucketDate);
+      await assetStore.loadBucket(bucket.yearMonth);
 
       if (!get(isSelectingAllAssets)) {
         assetInteraction.clearMultiselect();
         break; // Cancelled
       }
-      assetInteraction.selectAssets(assetsSnapshot(bucket.getAssets()));
+      assetInteraction.selectAssets(assetsSnapshot([...bucket.assetsIterator()]));
 
       for (const dateGroup of bucket.dateGroups) {
         assetInteraction.addGroupToMultiselectGroup(dateGroup.groupTitle);

web/src/lib/utils/focus-util.ts

@@ -12,28 +12,43 @@ export const setDefaultTabbleOptions = (options: TabbableOpts) => {
 export const getTabbable = (container: Element, includeContainer: boolean = false) =>
   tabbable(container, { ...defaultOpts, includeContainer });
 
-export const focusNext = (selector: (element: HTMLElement | SVGElement) => boolean, forwardDirection: boolean) => {
-  const focusElements = focusable(document.body, { includeContainer: true });
-  const current = document.activeElement as HTMLElement;
-  const index = focusElements.indexOf(current);
-  if (index === -1) {
-    for (const element of focusElements) {
-      if (selector(element)) {
-        element.focus();
-        return;
-      }
-    }
-    focusElements[0].focus();
+export const moveFocus = (
+  selector: (element: HTMLElement | SVGElement) => boolean,
+  direction: 'previous' | 'next',
+): void => {
+  const focusableElements = focusable(document.body, { includeContainer: true });
+
+  if (focusableElements.length === 0) {
     return;
   }
-  const totalElements = focusElements.length;
-  let i = index;
+
+  const currentElement = document.activeElement as HTMLElement | null;
+  const currentIndex = currentElement ? focusableElements.indexOf(currentElement) : -1;
+
+  // If no element is focused, focus the first matching element or the first focusable element
+  if (currentIndex === -1) {
+    const firstMatchingElement = focusableElements.find((element) => selector(element));
+    if (firstMatchingElement) {
+      firstMatchingElement.focus();
+    } else if (focusableElements[0]) {
+      focusableElements[0].focus();
+    }
+    return;
+  }
+
+  // Calculate the step direction
+  const step = direction === 'next' ? 1 : -1;
+  const totalElements = focusableElements.length;
+
+  // Search for the next focusable element that matches the selector
+  let nextIndex = currentIndex;
   do {
-    i = (i + (forwardDirection ? 1 : -1) + totalElements) % totalElements;
-    const next = focusElements[i];
-    if (isTabbable(next) && selector(next)) {
-      next.focus();
+    nextIndex = (nextIndex + step + totalElements) % totalElements;
+    const candidateElement = focusableElements[nextIndex];
+
+    if (isTabbable(candidateElement) && selector(candidateElement)) {
+      candidateElement.focus();
       break;
     }
-  } while (i !== index);
+  } while (nextIndex !== currentIndex);
 };

web/src/lib/utils/invocationTracker.ts

@@ -0,0 +1,53 @@
+/**
+ * Tracks the state of asynchronous invocations to handle race conditions and stale operations.
+ * This class helps manage concurrent operations by tracking which invocations are active
+ * and allowing operations to check if they're still valid.
+ */
+export class InvocationTracker {
+  /** Counter for the number of invocations that have been started */
+  invocationsStarted = 0;
+  /** Counter for the number of invocations that have been completed */
+  invocationsEnded = 0;
+
+  constructor() {}
+
+  /**
+   * Starts a new invocation and returns an object with utilities to manage the invocation lifecycle.
+   * @returns  An object containing methods to manage the invocation:
+   *   - isInvalidInvocationError: Checks if an error is an invalid invocation error
+   *   - checkStillValid: Throws an error if the invocation is no longer valid
+   *   - endInvocation: Marks the invocation as complete
+   */
+  startInvocation() {
+    this.invocationsStarted++;
+    const invocation = this.invocationsStarted;
+
+    return {
+      /**
+       * Throws an error if this invocation is no longer valid
+       * @throws {Error} If the invocation is no longer valid
+       */
+      isStillValid: () => {
+        if (invocation !== this.invocationsStarted) {
+          return false;
+        }
+        return true;
+      },
+
+      /**
+       * Marks this invocation as complete
+       */
+      endInvocation: () => {
+        this.invocationsEnded = invocation;
+      },
+    };
+  }
+
+  /**
+   * Checks if there are any active invocations
+   * @returns True if there are active invocations, false otherwise
+   */
+  isActive() {
+    return this.invocationsStarted !== this.invocationsEnded;
+  }
+}

web/src/lib/utils/thumbnail-util.spec.ts

@@ -56,12 +56,21 @@ describe('getAltText', () => {
       people?: Person[];
       expected: string;
     }) => {
+      const testDate = new Date('2024-01-01T12:00:00.000Z');
       const asset: TimelineAsset = {
         id: 'test-id',
         ownerId: 'test-owner',
         ratio: 1,
         thumbhash: null,
-        localDateTime: '2024-01-01T12:00:00.000Z',
+        localDateTime: {
+          year: testDate.getUTCFullYear(),
+          month: testDate.getUTCMonth() + 1, // Note: getMonth() is 0-based
+          day: testDate.getUTCDate(),
+          hour: testDate.getUTCHours(),
+          minute: testDate.getUTCMinutes(),
+          second: testDate.getUTCSeconds(),
+          millisecond: testDate.getUTCMilliseconds(),
+        },
         visibility: AssetVisibility.Timeline,
         isFavorite: false,
         isTrashed: false,

web/src/lib/utils/thumbnail-util.ts

@@ -1,8 +1,8 @@
 import type { TimelineAsset } from '$lib/stores/assets-store.svelte';
 import { locale } from '$lib/stores/preferences.store';
+import { fromTimelinePlainDateTime } from '$lib/utils/timeline-util';
 import { t } from 'svelte-i18n';
 import { derived, get } from 'svelte/store';
-import { fromLocalDateTime } from './timeline-util';
 
 /**
  * Calculate thumbnail size based on number of assets and viewport width
@@ -40,7 +40,10 @@ export function getThumbnailSize(assetCount: number, viewWidth: number): number
 
 export const getAltText = derived(t, ($t) => {
   return (asset: TimelineAsset) => {
-    const date = fromLocalDateTime(asset.localDateTime).toLocaleString({ dateStyle: 'long' }, { locale: get(locale) });
+    const date = fromTimelinePlainDateTime(asset.localDateTime).toJSDate().toLocaleString(get(locale), {
+      dateStyle: 'long',
+      timeZone: 'UTC',
+    });
     const hasPlace = asset.city && asset.country;
 
     const peopleCount = asset.people.length;

web/src/lib/utils/timeline-util.ts

@@ -1,15 +1,12 @@
 import type { TimelineAsset } from '$lib/stores/assets-store.svelte';
 import { locale } from '$lib/stores/preferences.store';
 import { getAssetRatio } from '$lib/utils/asset-utils';
-
 import { AssetTypeEnum, type AssetResponseDto } from '@immich/sdk';
-
-import { memoize } from 'lodash-es';
 import { DateTime, type LocaleOptions } from 'luxon';
 import { get } from 'svelte/store';
 
 export type ScrubberListener = (
-  bucketDate: string | undefined,
+  bucketDate: { year: number; month: number },
   overallScrollPercent: number,
   bucketScrollPercent: number,
 ) => void | Promise<void>;
@@ -17,8 +14,44 @@ export type ScrubberListener = (
 export const fromLocalDateTime = (localDateTime: string) =>
   DateTime.fromISO(localDateTime, { zone: 'UTC', locale: get(locale) });
 
+export const fromLocalDateTimeToObject = (localDateTime: string): TimelinePlainDateTime =>
+  (fromLocalDateTime(localDateTime) as DateTime<true>).toObject();
+
+export const fromTimelinePlainDateTime = (timelineDateTime: TimelinePlainDateTime): DateTime<true> =>
+  DateTime.fromObject(timelineDateTime, { zone: 'local', locale: get(locale) }) as DateTime<true>;
+
+export const fromTimelinePlainDate = (timelineYearMonth: TimelinePlainDate): DateTime<true> =>
+  DateTime.fromObject(
+    { year: timelineYearMonth.year, month: timelineYearMonth.month, day: timelineYearMonth.day },
+    { zone: 'local', locale: get(locale) },
+  ) as DateTime<true>;
+
+export const fromTimelinePlainYearMonth = (timelineYearMonth: TimelinePlainYearMonth): DateTime<true> =>
+  DateTime.fromObject(
+    { year: timelineYearMonth.year, month: timelineYearMonth.month },
+    { zone: 'local', locale: get(locale) },
+  ) as DateTime<true>;
+
 export const fromDateTimeOriginal = (dateTimeOriginal: string, timeZone: string) =>
-  DateTime.fromISO(dateTimeOriginal, { zone: timeZone });
+  DateTime.fromISO(dateTimeOriginal, { zone: timeZone, locale: get(locale) });
+
+export const toISOLocalDateTime = (timelineYearMonth: TimelinePlainYearMonth): string =>
+  (fromTimelinePlainYearMonth(timelineYearMonth).setZone('UTC', { keepLocalTime: true }) as DateTime<true>).toISO();
+
+export function formatBucketTitle(_date: DateTime): string {
+  if (!_date.isValid) {
+    return _date.toString();
+  }
+  const date = _date as DateTime<true>;
+  return date.toLocaleString(
+    {
+      month: 'short',
+      year: 'numeric',
+      timeZone: 'UTC',
+    },
+    { locale: get(locale) },
+  );
+}
 
 export function formatGroupTitle(_date: DateTime): string {
   if (!_date.isValid) {
@@ -60,8 +93,6 @@ export function formatGroupTitle(_date: DateTime): string {
 export const getDateLocaleString = (date: DateTime, opts?: LocaleOptions): string =>
   date.toLocaleString(DateTime.DATE_MED_WITH_WEEKDAY, opts);
 
-export const formatDateGroupTitle = memoize(formatGroupTitle);
-
 export const toTimelineAsset = (unknownAsset: AssetResponseDto | TimelineAsset): TimelineAsset => {
   if (isTimelineAsset(unknownAsset)) {
     return unknownAsset;
@@ -78,7 +109,7 @@ export const toTimelineAsset = (unknownAsset: AssetResponseDto | TimelineAsset):
     ownerId: assetResponse.ownerId,
     ratio,
     thumbhash: assetResponse.thumbhash,
-    localDateTime: assetResponse.localDateTime,
+    localDateTime: fromLocalDateTimeToObject(assetResponse.localDateTime),
     isFavorite: assetResponse.isFavorite,
     visibility: assetResponse.visibility,
     isTrashed: assetResponse.isTrashed,
@@ -93,5 +124,46 @@ export const toTimelineAsset = (unknownAsset: AssetResponseDto | TimelineAsset):
     people,
   };
 };
+
 export const isTimelineAsset = (unknownAsset: AssetResponseDto | TimelineAsset): unknownAsset is TimelineAsset =>
   (unknownAsset as TimelineAsset).ratio !== undefined;
+
+export const plainDateTimeCompare = (ascending: boolean, a: TimelinePlainDateTime, b: TimelinePlainDateTime) => {
+  const [aDateTime, bDateTime] = ascending ? [a, b] : [b, a];
+
+  if (aDateTime.year !== bDateTime.year) {
+    return aDateTime.year - bDateTime.year;
+  }
+  if (aDateTime.month !== bDateTime.month) {
+    return aDateTime.month - bDateTime.month;
+  }
+  if (aDateTime.day !== bDateTime.day) {
+    return aDateTime.day - bDateTime.day;
+  }
+  if (aDateTime.hour !== bDateTime.hour) {
+    return aDateTime.hour - bDateTime.hour;
+  }
+  if (aDateTime.minute !== bDateTime.minute) {
+    return aDateTime.minute - bDateTime.minute;
+  }
+  if (aDateTime.second !== bDateTime.second) {
+    return aDateTime.second - bDateTime.second;
+  }
+  return aDateTime.millisecond - bDateTime.millisecond;
+};
+
+export type TimelinePlainDateTime = TimelinePlainDate & {
+  hour: number;
+  minute: number;
+  second: number;
+  millisecond: number;
+};
+
+export type TimelinePlainDate = TimelinePlainYearMonth & {
+  day: number;
+};
+
+export type TimelinePlainYearMonth = {
+  year: number;
+  month: number;
+};