refactor: timeline manager renames (#19007)

* refactor: timeline manager renames

* refactor(web): improve timeline manager naming consistency

- Rename AddContext → GroupInsertionCache for clearer purpose
- Rename TimelineDay → DayGroup for better clarity
- Rename TimelineMonth → MonthGroup for better clarity
- Replace all "bucket" references with "monthGroup" terminology
- Update all component props, method names, and variable references
- Maintain consistent naming patterns across TypeScript and Svelte files

* refactor(web): rename buckets to months in timeline manager

- Rename TimelineManager.buckets property to months
- Update all store.buckets references to store.months
- Use 'month' shorthand for monthGroup arguments (not method names)
- Update component templates and test files for consistency
- Maintain API-related 'bucket' terminology (bucketHeight, getTimeBucket)

* refactor(web): rename assetStore to timelineManager and update types

- Rename assetStore variables to timelineManager in all .svelte files
- Update parameter names in actions.ts and asset-utils.ts functions
- Rename AssetStoreLayoutOptions to TimelineManagerLayoutOptions
- Rename AssetStoreOptions to TimelineManagerOptions
- Move assets-store.spec.ts to timeline-manager.spec.ts

* refactor(web): rename intersectingAssets to viewerAssets and fix property references

- Rename intersectingAssets to viewerAssets in DayGroup and MonthGroup classes
- Update arrow function parameters to use viewerAsset/viewAsset shorthand
- Rename topIntersectingBucket to topIntersectingMonthGroup
- Fix dateGroups references to dayGroups in asset-utils.ts and album page
- Update template loops and variable names in Svelte components

* refactor(web): rename #initializeTimeBuckets to #initializeMonthGroups and bucketDateFormatted to monthGroupTitle

* refactor(web): rename monthGroupHeight to height

* refactor(web): rename bucketCount to assetsCount, bucketsIterator to monthGroupIterator, and related properties

* refactor(web): rename count to assetCount in TimelineManager

* refactor(web): rename LiteBucket to ScrubberMonth and update scrubber variables

- Rename LiteBucket type to ScrubberMonth
- Rename bucketDateFormattted to title in ScrubberMonth type
- Rename bucketPercentY to monthGroupPercentY in scrubber component
- Rename scrubBucket to scrubberMonth and scrubBucketPercent to scrubberMonthPercent

* fix remaining refs to bucket

* reset submodule to correct commit

* reset submodule to correct commit

* refactor(web): extract TimelineManager internals into separate modules

- Move search-related functions to internal/search-support.svelte.ts
- Extract websocket event handling into WebsocketSupport class
- Move utility functions (updateObject, isMismatched) to internal/utils.svelte.ts
- Update imports in tests to use new module structure

* refactor(web): extract intersection logic from TimelineManager

- Create intersection-support.svelte.ts with updateIntersection and calculateIntersecting functions
- Remove private intersection methods from TimelineManager
- Export findMonthGroupForAsset from search-support for reuse
- Update TimelineManager to use the extracted intersection functions

* refactor(web): rename a few methods in intersecting

* refactor(web): rename a few methods in intersecting

* refactor(web): extract layout logic from TimelineManager

- Create layout-support.svelte.ts with updateGeometry and layoutMonthGroup functions
- Remove private layout methods from TimelineManager
- Update TimelineManager to use the extracted layout functions
- Remove unused UpdateGeometryOptions import

* refactor(web): extract asset operations from TimelineManager

- Create operations-support.svelte.ts with addAssetsToMonthGroups and runAssetOperation functions
- Remove private asset operation methods from TimelineManager
- Update TimelineManager to use extracted operation functions with proper AssetOrder handling
- Rename getMonthGroupIndexByAssetId to getMonthGroupByAssetId for consistency
- Move utility functions from utils.svelte.ts to internal/utils.svelte.ts
- Fix method name references in asset-grid.svelte and tests

* refactor(web): extract loading logic from TimelineManager

- Create load-support.svelte.ts with loadFromTimeBuckets function
- Extract time bucket loading, album asset handling, and error logging
- Simplify TimelineManager's loadMonthGroup method to use extracted function

* refresh timeline after archive keyboard shortcut

* remove debugger

* rename

* Review comments - remove shadowed var

* reduce indents - early return

* review comment

* refactor: simplify asset filtering in addAssets method

Replace for loop with filter operation for better readability

* fix: bad merge

* refactor(web): simplify timeline layout algorithm

- Replace rowSpaceRemaining array with direct cumulative width tracking
- Invert logic from tracking remaining space to tracking used space
- Fix spelling: cummulative to cumulative
- Rename lastRowHeight to currentRowHeight for clarity
- Remove confusing lastRow variable and simplify final height calculation
- Add explanatory comments for clarity
- Rename loop variable assetGroup to dayGroup for consistency

* simplify assetsIterator usage

* merge/lint

---------

Co-authored-by: Alex <alex.tran1502@gmail.com>
This commit is contained in:
Min Idzelis
2025-06-10 10:30:13 -04:00
committed by GitHub
parent 6499057b4c
commit 4b4ee5abf3
39 changed files with 2288 additions and 2139 deletions
@@ -0,0 +1,77 @@
import { TUNABLES } from '$lib/utils/tunables';
import type { MonthGroup } from '../month-group.svelte';
import type { TimelineManager } from '../timeline-manager.svelte';
const {
TIMELINE: { INTERSECTION_EXPAND_TOP, INTERSECTION_EXPAND_BOTTOM },
} = TUNABLES;
export function updateIntersectionMonthGroup(timelineManager: TimelineManager, month: MonthGroup) {
const actuallyIntersecting = calculateMonthGroupIntersecting(timelineManager, month, 0, 0);
let preIntersecting = false;
if (!actuallyIntersecting) {
preIntersecting = calculateMonthGroupIntersecting(
timelineManager,
month,
INTERSECTION_EXPAND_TOP,
INTERSECTION_EXPAND_BOTTOM,
);
}
month.intersecting = actuallyIntersecting || preIntersecting;
month.actuallyIntersecting = actuallyIntersecting;
if (preIntersecting || actuallyIntersecting) {
timelineManager.clearDeferredLayout(month);
}
}
/**
* General function to check if a rectangular region intersects with a window.
* @param regionTop - Top position of the region to check
* @param regionBottom - Bottom position of the region to check
* @param windowTop - Top position of the window
* @param windowBottom - Bottom position of the window
* @returns true if the region intersects with the window
*/
export function isIntersecting(regionTop: number, regionBottom: number, windowTop: number, windowBottom: number) {
return (
(regionTop >= windowTop && regionTop < windowBottom) ||
(regionBottom >= windowTop && regionBottom < windowBottom) ||
(regionTop < windowTop && regionBottom >= windowBottom)
);
}
export function calculateMonthGroupIntersecting(
timelineManager: TimelineManager,
monthGroup: MonthGroup,
expandTop: number,
expandBottom: number,
) {
const monthGroupTop = monthGroup.top;
const monthGroupBottom = monthGroupTop + monthGroup.height;
const topWindow = timelineManager.visibleWindow.top - expandTop;
const bottomWindow = timelineManager.visibleWindow.bottom + expandBottom;
return isIntersecting(monthGroupTop, monthGroupBottom, topWindow, bottomWindow);
}
/**
* Calculate intersection for viewer assets with additional parameters like header height and scroll compensation
*/
export function calculateViewerAssetIntersecting(
timelineManager: TimelineManager,
positionTop: number,
positionHeight: number,
expandTop: number = INTERSECTION_EXPAND_TOP,
expandBottom: number = INTERSECTION_EXPAND_BOTTOM,
) {
const scrollCompensationHeightDelta = timelineManager.scrollCompensation?.heightDelta ?? 0;
const topWindow =
timelineManager.visibleWindow.top - timelineManager.headerHeight - expandTop + scrollCompensationHeightDelta;
const bottomWindow =
timelineManager.visibleWindow.bottom + timelineManager.headerHeight + expandBottom + scrollCompensationHeightDelta;
const positionBottom = positionTop + positionHeight;
return isIntersecting(positionTop, positionBottom, topWindow, bottomWindow);
}
@@ -0,0 +1,70 @@
import type { MonthGroup } from '../month-group.svelte';
import type { TimelineManager } from '../timeline-manager.svelte';
import type { UpdateGeometryOptions } from '../types';
export function updateGeometry(timelineManager: TimelineManager, month: MonthGroup, options: UpdateGeometryOptions) {
const { invalidateHeight, noDefer = false } = options;
if (invalidateHeight) {
month.isHeightActual = false;
}
if (!month.isLoaded) {
const viewportWidth = timelineManager.viewportWidth;
if (!month.isHeightActual) {
const unwrappedWidth = (3 / 2) * month.assetsCount * timelineManager.rowHeight * (7 / 10);
const rows = Math.ceil(unwrappedWidth / viewportWidth);
const height = 51 + Math.max(1, rows) * timelineManager.rowHeight;
month.height = height;
}
return;
}
layoutMonthGroup(timelineManager, month, noDefer);
}
export function layoutMonthGroup(timelineManager: TimelineManager, month: MonthGroup, noDefer: boolean = false) {
let cumulativeHeight = 0;
let cumulativeWidth = 0;
let currentRowHeight = 0;
let dayGroupRow = 0;
let dayGroupCol = 0;
const options = timelineManager.createLayoutOptions();
for (const dayGroup of month.dayGroups) {
dayGroup.layout(options, noDefer);
// Calculate space needed for this item (including gap if not first in row)
const spaceNeeded = dayGroup.width + (dayGroupCol > 0 ? timelineManager.gap : 0);
const fitsInCurrentRow = cumulativeWidth + spaceNeeded <= timelineManager.viewportWidth;
if (fitsInCurrentRow) {
dayGroup.row = dayGroupRow;
dayGroup.col = dayGroupCol++;
dayGroup.left = cumulativeWidth;
dayGroup.top = cumulativeHeight;
cumulativeWidth += dayGroup.width + timelineManager.gap;
} else {
// Move to next row
cumulativeHeight += currentRowHeight;
cumulativeWidth = 0;
dayGroupRow++;
dayGroupCol = 0;
// Position at start of new row
dayGroup.row = dayGroupRow;
dayGroup.col = dayGroupCol;
dayGroup.left = 0;
dayGroup.top = cumulativeHeight;
dayGroupCol++;
cumulativeWidth += dayGroup.width + timelineManager.gap;
}
currentRowHeight = dayGroup.height + timelineManager.headerHeight;
}
// Add the height of the final row
cumulativeHeight += currentRowHeight;
month.height = cumulativeHeight;
month.isHeightActual = true;
}
@@ -0,0 +1,62 @@
import { authManager } from '$lib/managers/auth-manager.svelte';
import { toISOYearMonthUTC } from '$lib/utils/timeline-util';
import { getTimeBucket } from '@immich/sdk';
import type { MonthGroup } from '../month-group.svelte';
import type { TimelineManager } from '../timeline-manager.svelte';
import type { TimelineManagerOptions } from '../types';
import { layoutMonthGroup } from './layout-support.svelte';
export async function loadFromTimeBuckets(
timelineManager: TimelineManager,
monthGroup: MonthGroup,
options: TimelineManagerOptions,
signal: AbortSignal,
): Promise<void> {
if (monthGroup.getFirstAsset()) {
return;
}
const timeBucket = toISOYearMonthUTC(monthGroup.yearMonth);
const key = authManager.key;
const bucketResponse = await getTimeBucket(
{
...options,
timeBucket,
key,
},
{ signal },
);
if (!bucketResponse) {
return;
}
if (options.timelineAlbumId) {
const albumAssets = await getTimeBucket(
{
albumId: options.timelineAlbumId,
timeBucket,
key,
},
{ signal },
);
for (const id of albumAssets.id) {
timelineManager.albumAssets.add(id);
}
}
const unprocessedAssets = monthGroup.addAssets(bucketResponse);
if (unprocessedAssets.length > 0) {
console.error(
`Warning: getTimeBucket API returning assets not in requested month: ${monthGroup.yearMonth.month}, ${JSON.stringify(
unprocessedAssets.map((unprocessed) => ({
id: unprocessed.id,
localDateTime: unprocessed.localDateTime,
})),
)}`,
);
}
layoutMonthGroup(timelineManager, monthGroup);
}
@@ -0,0 +1,103 @@
import type { TimelinePlainDate } from '$lib/utils/timeline-util';
import { AssetOrder } from '@immich/sdk';
import { GroupInsertionCache } from '../group-insertion-cache.svelte';
import { MonthGroup } from '../month-group.svelte';
import type { TimelineManager } from '../timeline-manager.svelte';
import type { AssetOperation, TimelineAsset } from '../types';
import { updateGeometry } from './layout-support.svelte';
import { getMonthGroupByDate } from './search-support.svelte';
export function addAssetsToMonthGroups(
timelineManager: TimelineManager,
assets: TimelineAsset[],
options: { order: AssetOrder },
) {
if (assets.length === 0) {
return;
}
const addContext = new GroupInsertionCache();
const updatedMonthGroups = new Set<MonthGroup>();
const monthCount = timelineManager.months.length;
for (const asset of assets) {
let month = getMonthGroupByDate(timelineManager, asset.localDateTime);
if (!month) {
month = new MonthGroup(timelineManager, asset.localDateTime, 1, options.order);
month.isLoaded = true;
timelineManager.months.push(month);
}
month.addTimelineAsset(asset, addContext);
updatedMonthGroups.add(month);
}
if (timelineManager.months.length !== monthCount) {
timelineManager.months.sort((a, b) => {
return a.yearMonth.year === b.yearMonth.year
? b.yearMonth.month - a.yearMonth.month
: b.yearMonth.year - a.yearMonth.year;
});
}
for (const group of addContext.existingDayGroups) {
group.sortAssets(options.order);
}
for (const monthGroup of addContext.bucketsWithNewDayGroups) {
monthGroup.sortDayGroups();
}
for (const month of addContext.updatedBuckets) {
month.sortDayGroups();
updateGeometry(timelineManager, month, { invalidateHeight: true });
}
timelineManager.updateIntersections();
}
export function runAssetOperation(
timelineManager: TimelineManager,
ids: Set<string>,
operation: AssetOperation,
options: { order: AssetOrder },
) {
if (ids.size === 0) {
return { processedIds: new Set(), unprocessedIds: ids, changedGeometry: false };
}
const changedMonthGroups = new Set<MonthGroup>();
let idsToProcess = new Set(ids);
const idsProcessed = new Set<string>();
const combinedMoveAssets: { asset: TimelineAsset; date: TimelinePlainDate }[][] = [];
for (const month of timelineManager.months) {
if (idsToProcess.size > 0) {
const { moveAssets, processedIds, changedGeometry } = month.runAssetOperation(idsToProcess, operation);
if (moveAssets.length > 0) {
combinedMoveAssets.push(moveAssets);
}
idsToProcess = idsToProcess.difference(processedIds);
for (const id of processedIds) {
idsProcessed.add(id);
}
if (changedGeometry) {
changedMonthGroups.add(month);
}
}
}
if (combinedMoveAssets.length > 0) {
addAssetsToMonthGroups(
timelineManager,
combinedMoveAssets.flat().map((a) => a.asset),
options,
);
}
const changedGeometry = changedMonthGroups.size > 0;
for (const month of changedMonthGroups) {
updateGeometry(timelineManager, month, { invalidateHeight: true });
}
if (changedGeometry) {
timelineManager.updateIntersections();
}
return { unprocessedIds: idsToProcess, processedIds: idsProcessed, changedGeometry };
}
@@ -0,0 +1,146 @@
import { plainDateTimeCompare, type TimelinePlainYearMonth } from '$lib/utils/timeline-util';
import type { MonthGroup } from '../month-group.svelte';
import type { TimelineManager } from '../timeline-manager.svelte';
import type { AssetDescriptor, Direction, TimelineAsset } from '../types';
export async function getAssetWithOffset(
timelineManager: TimelineManager,
assetDescriptor: AssetDescriptor,
interval: 'asset' | 'day' | 'month' | 'year' = 'asset',
direction: Direction,
): Promise<TimelineAsset | undefined> {
const { asset, monthGroup } = findMonthGroupForAsset(timelineManager, assetDescriptor.id) ?? {};
if (!monthGroup || !asset) {
return;
}
switch (interval) {
case 'asset': {
return getAssetByAssetOffset(timelineManager, asset, monthGroup, direction);
}
case 'day': {
return getAssetByDayOffset(timelineManager, asset, monthGroup, direction);
}
case 'month': {
return getAssetByMonthOffset(timelineManager, monthGroup, direction);
}
case 'year': {
return getAssetByYearOffset(timelineManager, monthGroup, direction);
}
}
}
export function findMonthGroupForAsset(timelineManager: TimelineManager, id: string) {
for (const month of timelineManager.months) {
const asset = month.findAssetById({ id });
if (asset) {
return { monthGroup: month, asset };
}
}
}
export function getMonthGroupByDate(
timelineManager: TimelineManager,
targetYearMonth: TimelinePlainYearMonth,
): MonthGroup | undefined {
return timelineManager.months.find(
(month) => month.yearMonth.year === targetYearMonth.year && month.yearMonth.month === targetYearMonth.month,
);
}
async function getAssetByAssetOffset(
timelineManager: TimelineManager,
asset: TimelineAsset,
monthGroup: MonthGroup,
direction: Direction,
) {
const dayGroup = monthGroup.findDayGroupForAsset(asset);
for await (const targetAsset of timelineManager.assetsIterator({
startMonthGroup: monthGroup,
startDayGroup: dayGroup,
startAsset: asset,
direction,
})) {
if (asset.id !== targetAsset.id) {
return targetAsset;
}
}
}
async function getAssetByDayOffset(
timelineManager: TimelineManager,
asset: TimelineAsset,
monthGroup: MonthGroup,
direction: Direction,
) {
const dayGroup = monthGroup.findDayGroupForAsset(asset);
for await (const targetAsset of timelineManager.assetsIterator({
startMonthGroup: monthGroup,
startDayGroup: dayGroup,
startAsset: asset,
direction,
})) {
if (targetAsset.localDateTime.day !== asset.localDateTime.day) {
return targetAsset;
}
}
}
async function getAssetByMonthOffset(timelineManager: TimelineManager, month: MonthGroup, direction: Direction) {
for (const targetMonth of timelineManager.monthGroupIterator({ startMonthGroup: month, direction })) {
if (targetMonth.yearMonth.month !== month.yearMonth.month) {
const { value, done } = await timelineManager.assetsIterator({ startMonthGroup: targetMonth, direction }).next();
return done ? undefined : value;
}
}
}
async function getAssetByYearOffset(timelineManager: TimelineManager, month: MonthGroup, direction: Direction) {
for (const targetMonth of timelineManager.monthGroupIterator({ startMonthGroup: month, direction })) {
if (targetMonth.yearMonth.year !== month.yearMonth.year) {
const { value, done } = await timelineManager.assetsIterator({ startMonthGroup: targetMonth, direction }).next();
return done ? undefined : value;
}
}
}
export async function retrieveRange(timelineManager: TimelineManager, start: AssetDescriptor, end: AssetDescriptor) {
let { asset: startAsset, monthGroup: startMonthGroup } = findMonthGroupForAsset(timelineManager, start.id) ?? {};
if (!startMonthGroup || !startAsset) {
return [];
}
let { asset: endAsset, monthGroup: endMonthGroup } = findMonthGroupForAsset(timelineManager, end.id) ?? {};
if (!endMonthGroup || !endAsset) {
return [];
}
let direction: Direction = 'earlier';
if (plainDateTimeCompare(true, startAsset.localDateTime, endAsset.localDateTime) < 0) {
[startAsset, endAsset] = [endAsset, startAsset];
[startMonthGroup, endMonthGroup] = [endMonthGroup, startMonthGroup];
direction = 'earlier';
}
const range: TimelineAsset[] = [];
const startDayGroup = startMonthGroup.findDayGroupForAsset(startAsset);
for await (const targetAsset of timelineManager.assetsIterator({
startMonthGroup,
startDayGroup,
startAsset,
direction,
})) {
range.push(targetAsset);
if (targetAsset.id === endAsset.id) {
break;
}
}
return range;
}
export function findMonthGroupForDate(timelineManager: TimelineManager, targetYearMonth: TimelinePlainYearMonth) {
for (const month of timelineManager.months) {
const { year, month: monthNum } = month.yearMonth;
if (monthNum === targetYearMonth.month && year === targetYearMonth.year) {
return month;
}
}
}
@@ -0,0 +1,28 @@
// eslint-disable-next-line @typescript-eslint/no-explicit-any
export function updateObject(target: any, source: any): boolean {
if (!target) {
return false;
}
let updated = false;
for (const key in source) {
if (!Object.prototype.hasOwnProperty.call(source, key)) {
continue;
}
if (key === '__proto__' || key === 'constructor') {
continue;
}
const isDate = target[key] instanceof Date;
if (typeof target[key] === 'object' && !isDate) {
updated = updated || updateObject(target[key], source[key]);
} else {
if (target[key] !== source[key]) {
target[key] = source[key];
updated = true;
}
}
}
return updated;
}
export function isMismatched<T>(option: T | undefined, value: T): boolean {
return option === undefined ? false : option !== value;
}
@@ -0,0 +1,85 @@
import type { TimelineManager } from '$lib/managers/timeline-manager/timeline-manager.svelte';
import type { PendingChange, TimelineAsset } from '$lib/managers/timeline-manager/types';
import { websocketEvents } from '$lib/stores/websocket';
import { toTimelineAsset } from '$lib/utils/timeline-util';
import { throttle } from 'lodash-es';
import type { Unsubscriber } from 'svelte/store';
export class WebsocketSupport {
#pendingChanges: PendingChange[] = [];
#unsubscribers: Unsubscriber[] = [];
#timelineManager: TimelineManager;
#processPendingChanges = throttle(() => {
const { add, update, remove } = this.#getPendingChangeBatches();
if (add.length > 0) {
this.#timelineManager.addAssets(add);
}
if (update.length > 0) {
this.#timelineManager.updateAssets(update);
}
if (remove.length > 0) {
this.#timelineManager.removeAssets(remove);
}
this.#pendingChanges = [];
}, 2500);
constructor(timeineManager: TimelineManager) {
this.#timelineManager = timeineManager;
}
connectWebsocketEvents() {
this.#unsubscribers.push(
websocketEvents.on('on_upload_success', (asset) =>
this.#addPendingChanges({ type: 'add', values: [toTimelineAsset(asset)] }),
),
websocketEvents.on('on_asset_trash', (ids) => this.#addPendingChanges({ type: 'trash', values: ids })),
websocketEvents.on('on_asset_update', (asset) =>
this.#addPendingChanges({ type: 'update', values: [toTimelineAsset(asset)] }),
),
websocketEvents.on('on_asset_delete', (id: string) => this.#addPendingChanges({ type: 'delete', values: [id] })),
);
}
disconnectWebsocketEvents() {
for (const unsubscribe of this.#unsubscribers) {
unsubscribe();
}
this.#unsubscribers = [];
}
#addPendingChanges(...changes: PendingChange[]) {
this.#pendingChanges.push(...changes);
this.#processPendingChanges();
}
#getPendingChangeBatches() {
const batch: {
add: TimelineAsset[];
update: TimelineAsset[];
remove: string[];
} = {
add: [],
update: [],
remove: [],
};
for (const { type, values } of this.#pendingChanges) {
switch (type) {
case 'add': {
batch.add.push(...values);
break;
}
case 'update': {
batch.update.push(...values);
break;
}
case 'delete':
case 'trash': {
batch.remove.push(...values);
break;
}
}
}
return batch;
}
}