feat: added orphan assets and new info panel for the asset dialog

Signed-off-by: Varun <varun@skcript.com>
This commit is contained in:
Varun committed 2026-04-06 19:55:38 +05:30
1 parent 11e88526c7
commit a2916b6ee7
10 files changed
+1437 -5

No files matched your search

+549
View File
@@ -0,0 +1,549 @@
# Orphan Asset Finder Implementation Plan
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
**Goal:** Build a page that finds "orphaned" assets — those not in albums, without detected people, missing location, or never favorited — with combinable checkbox filters, asset grid, and bulk actions (add to album, trash, delete).
**Architecture:** New API route queries Immich's DB via Drizzle with LEFT JOINs to detect orphan conditions. Frontend page follows the empty-videos pattern: filters in Header, AssetGrid with PhotoSelectionContext, FloatingBar with bulk actions. Sidebar entry added.
**Tech Stack:** Next.js API route, Drizzle ORM (PostgreSQL), React, Tailwind, existing shared components (PageLayout, Header, FloatingBar, AssetGrid, AlbumSelectorDialog, AlertDialog).
---
### Task 1: Add API route for orphan assets
**Files:**
- Create: `src/pages/api/assets/orphan-finder.ts`
**Step 1: Create the API route**
```typescript
import { db } from "@/config/db";
import { getCurrentUser } from "@/handlers/serverUtils/user.utils";
import { NextApiRequest, NextApiResponse } from "next";
import { and, eq, isNull, isNotNull, sql, desc, asc, not } from "drizzle-orm";
import { assets } from "@/schema/assets.schema";
import { exif } from "@/schema";
import { albumsAssetsAssets } from "@/schema/albumAssetsAssets.schema";
import { assetFaces } from "@/schema/assetFaces.schema";
import { isFlipped } from "@/helpers/asset.helper";
export default async function handler(
req: NextApiRequest,
res: NextApiResponse
) {
const currentUser = await getCurrentUser(req);
if (!currentUser) {
return res.status(401).json({ message: "Unauthorized" });
}
const {
notInAlbum,
noPeople,
noLocation,
notFavorited,
type,
limit = "100",
page = "1",
} = req.query as Record<string, string>;
const limitNum = parseInt(limit, 10);
const pageNum = parseInt(page, 10);
// Build conditions
const conditions = [
eq(assets.ownerId, currentUser.id),
eq(assets.visibility, "timeline"),
eq(assets.status, "active"),
isNull(assets.deletedAt),
];
if (type && type !== "ALL") {
conditions.push(eq(assets.type, type));
}
if (notFavorited === "true") {
conditions.push(eq(assets.isFavorite, false));
}
if (noLocation === "true") {
conditions.push(isNull(exif.latitude));
}
// Subquery approach for notInAlbum and noPeople
const notInAlbumCondition = notInAlbum === "true"
? sql`NOT EXISTS (SELECT 1 FROM "album_asset" aa WHERE aa."assetId" = ${assets.id})`
: undefined;
const noPeopleCondition = noPeople === "true"
? sql`NOT EXISTS (SELECT 1 FROM "asset_face" af WHERE af."assetId" = ${assets.id} AND af."personId" IS NOT NULL)`
: undefined;
if (notInAlbumCondition) conditions.push(notInAlbumCondition);
if (noPeopleCondition) conditions.push(noPeopleCondition);
// At least one orphan filter must be active
const hasOrphanFilter = notInAlbum === "true" || noPeople === "true" || noLocation === "true" || notFavorited === "true";
if (!hasOrphanFilter) {
return res.status(400).json({ message: "At least one orphan filter is required" });
}
const dbAssets = await db
.selectDistinctOn([assets.id], {
id: assets.id,
deviceId: assets.deviceId,
type: assets.type,
originalPath: assets.originalPath,
isFavorite: assets.isFavorite,
duration: assets.duration,
originalFileName: assets.originalFileName,
deletedAt: assets.deletedAt,
localDateTime: assets.localDateTime,
exifImageWidth: exif.exifImageWidth,
exifImageHeight: exif.exifImageHeight,
ownerId: assets.ownerId,
dateTimeOriginal: exif.dateTimeOriginal,
orientation: exif.orientation,
})
.from(assets)
.leftJoin(exif, eq(assets.id, exif.assetId))
.where(and(...conditions))
.orderBy(assets.id, desc(assets.localDateTime))
.limit(limitNum)
.offset((pageNum - 1) * limitNum);
const cleanedAssets = dbAssets.map((asset) => ({
...asset,
exifImageHeight: isFlipped(asset?.orientation) ? asset?.exifImageWidth : asset?.exifImageHeight,
exifImageWidth: isFlipped(asset?.orientation) ? asset?.exifImageHeight : asset?.exifImageWidth,
orientation: asset?.orientation,
}));
return res.status(200).json(cleanedAssets);
}
```
**Step 2: Commit**
```bash
git add src/pages/api/assets/orphan-finder.ts
git commit -m "feat: add orphan finder API route"
```
---
### Task 2: Add route constant and handler function
**Files:**
- Modify: `src/config/routes.ts`
- Modify: `src/handlers/api/asset.handler.ts`
**Step 1: Add route constant**
In `src/config/routes.ts`, add after `LIST_EMPTY_VIDEOS_PATH`:
```typescript
export const LIST_ORPHAN_ASSETS_PATH = BASE_API_ENDPOINT + "/assets/orphan-finder";
```
**Step 2: Add handler function**
In `src/handlers/api/asset.handler.ts`, add import and function:
Add `LIST_ORPHAN_ASSETS_PATH` to the imports from `@/config/routes`.
Add this function:
```typescript
export interface IOrphanFilters {
notInAlbum?: boolean;
noPeople?: boolean;
noLocation?: boolean;
notFavorited?: boolean;
type?: string;
limit?: number;
page?: number;
}
export const listOrphanAssets = async (filters: IOrphanFilters): Promise<IAsset[]> => {
const params: Record<string, string> = {};
if (filters.notInAlbum) params.notInAlbum = "true";
if (filters.noPeople) params.noPeople = "true";
if (filters.noLocation) params.noLocation = "true";
if (filters.notFavorited) params.notFavorited = "true";
if (filters.type) params.type = filters.type;
if (filters.limit) params.limit = String(filters.limit);
if (filters.page) params.page = String(filters.page);
return API.get(LIST_ORPHAN_ASSETS_PATH, params).then((assets) => assets.map(cleanUpAsset));
}
```
**Step 3: Commit**
```bash
git add src/config/routes.ts src/handlers/api/asset.handler.ts
git commit -m "feat: add orphan finder route constant and handler"
```
---
### Task 3: Create the Orphan Finder page
**Files:**
- Create: `src/pages/assets/orphan-finder.tsx`
**Step 1: Create the page**
Follow the empty-videos pattern: PageLayout, Header with filters, PhotoSelectionContext, AssetGrid, FloatingBar with bulk actions.
```tsx
import PageLayout from '@/components/layouts/PageLayout'
import Header from '@/components/shared/Header'
import Loader from '@/components/ui/loader'
import { listOrphanAssets, deleteAssets, IOrphanFilters } from '@/handlers/api/asset.handler'
import { addAssetToAlbum, createAlbumWithAssets } from '@/handlers/api/album.handler'
import { IAsset } from '@/types/asset'
import React, { useEffect, useState, useMemo } from 'react'
import { Camera, Trash2, Trash, Search } from 'lucide-react'
import { humanizeNumber } from '@/helpers/string.helper'
import PhotoSelectionContext, { IPhotoSelectionContext } from '@/contexts/PhotoSelectionContext'
import FloatingBar from '@/components/shared/FloatingBar'
import { Button } from '@/components/ui/button'
import { AlertDialog } from '@/components/ui/alert-dialog'
import AssetGrid from '@/components/shared/AssetGrid'
import { Checkbox } from '@/components/ui/checkbox'
import { Label } from '@/components/ui/label'
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
import AlbumSelectorDialog from '@/components/albums/AlbumSelectorDialog'
import { IAlbum } from '@/types/album'
import { toast } from '@/components/ui/use-toast'
export default function OrphanFinderPage() {
const [assets, setAssets] = useState<IAsset[]>([])
const [loading, setLoading] = useState(false)
const [errorMessage, setErrorMessage] = useState('')
const [filters, setFilters] = useState<IOrphanFilters>({
notInAlbum: true,
noPeople: false,
noLocation: false,
notFavorited: false,
type: 'ALL',
limit: 200,
page: 1,
})
const [contextState, setContextState] = useState<IPhotoSelectionContext>({
selectedIds: [],
assets: [],
config: {
albumId: '',
sort: "fileOriginalDate",
sortOrder: "asc"
},
updateContext: (newConfig: Partial<IPhotoSelectionContext>) => {
setContextState(prevState => ({
...prevState,
...newConfig,
config: newConfig.config ? { ...prevState.config, ...newConfig.config } : prevState.config
}));
}
});
const selectedAssets = useMemo(() =>
contextState.assets.filter((a) => contextState.selectedIds.includes(a.id)),
[contextState.assets, contextState.selectedIds]
);
const hasActiveFilter = filters.notInAlbum || filters.noPeople || filters.noLocation || filters.notFavorited;
const fetchOrphans = async () => {
if (!hasActiveFilter) return;
setLoading(true)
setErrorMessage('')
listOrphanAssets(filters)
.then((fetchedAssets) => {
setAssets(fetchedAssets)
contextState.updateContext({ assets: fetchedAssets, selectedIds: [] })
})
.catch((error) => {
setErrorMessage(error.message || 'Failed to load orphan assets')
})
.finally(() => {
setLoading(false)
})
}
useEffect(() => {
fetchOrphans()
}, [filters])
const handleDelete = () => {
return deleteAssets(contextState.selectedIds, { force: true }).then(() => {
const newAssets = contextState.assets.filter((a) => !contextState.selectedIds.includes(a.id));
setAssets(newAssets)
contextState.updateContext({ selectedIds: [], assets: newAssets });
})
}
const handleTrash = () => {
return deleteAssets(contextState.selectedIds, { force: false }).then(() => {
const newAssets = contextState.assets.filter((a) => !contextState.selectedIds.includes(a.id));
setAssets(newAssets)
contextState.updateContext({ selectedIds: [], assets: newAssets });
})
}
const handleAddToAlbum = async (album: IAlbum) => {
await addAssetToAlbum(album.id, contextState.selectedIds);
toast({ title: "Success", description: `Added ${contextState.selectedIds.length} asset(s) to "${album.albumName}"` });
// Re-fetch if "not in album" filter is active (assets may no longer be orphans)
if (filters.notInAlbum) {
fetchOrphans();
}
}
const handleCreateAlbumWithAssets = async (data: { albumName: string }) => {
return createAlbumWithAssets(data.albumName, contextState.selectedIds).then(() => {
if (filters.notInAlbum) {
fetchOrphans();
}
});
}
const handleFilterToggle = (key: keyof IOrphanFilters) => {
setFilters(prev => ({ ...prev, [key]: !prev[key], page: 1 }));
}
const renderContent = () => {
if (!hasActiveFilter) {
return (
<div className="text-center py-8 text-gray-500">
Select at least one filter to find orphan assets.
</div>
);
}
if (loading) return <Loader />
if (errorMessage) return <div className="text-red-500 p-4">{errorMessage}</div>
return (
<div className="p-4">
{assets.length === 0 ? (
<div className="text-center py-8 text-gray-500">
<Search size={48} className="mx-auto text-gray-400 mb-4" />
<h3 className="text-lg font-medium text-gray-900 dark:text-white mb-2">No orphan assets found</h3>
<p>All your assets are well-organized with the current filters.</p>
</div>
) : (
<AssetGrid
assets={assets}
selectable={true}
onSelectionChange={(ids) => contextState.updateContext({ selectedIds: ids })}
/>
)}
</div>
)
}
return (
<PageLayout className="!p-0 !mb-0 relative pb-20">
<Header
leftComponent="Orphan Finder"
rightComponent={
<div className="flex items-center gap-4">
<div className="flex items-center gap-3">
<div className="flex items-center gap-1.5">
<Checkbox
id="notInAlbum"
checked={filters.notInAlbum}
onCheckedChange={() => handleFilterToggle('notInAlbum')}
/>
<Label htmlFor="notInAlbum" className="text-sm cursor-pointer">No Album</Label>
</div>
<div className="flex items-center gap-1.5">
<Checkbox
id="noPeople"
checked={filters.noPeople}
onCheckedChange={() => handleFilterToggle('noPeople')}
/>
<Label htmlFor="noPeople" className="text-sm cursor-pointer">No People</Label>
</div>
<div className="flex items-center gap-1.5">
<Checkbox
id="noLocation"
checked={filters.noLocation}
onCheckedChange={() => handleFilterToggle('noLocation')}
/>
<Label htmlFor="noLocation" className="text-sm cursor-pointer">No Location</Label>
</div>
<div className="flex items-center gap-1.5">
<Checkbox
id="notFavorited"
checked={filters.notFavorited}
onCheckedChange={() => handleFilterToggle('notFavorited')}
/>
<Label htmlFor="notFavorited" className="text-sm cursor-pointer">Not Favorited</Label>
</div>
</div>
<Select
value={filters.type}
onValueChange={(value) => setFilters(prev => ({ ...prev, type: value, page: 1 }))}
>
<SelectTrigger className="w-28 h-8">
<SelectValue />
</SelectTrigger>
<SelectContent>
<SelectItem value="ALL">All Types</SelectItem>
<SelectItem value="IMAGE">Images</SelectItem>
<SelectItem value="VIDEO">Videos</SelectItem>
</SelectContent>
</Select>
{!loading && assets.length > 0 && (
<div className="flex items-center gap-1 text-sm text-gray-700 dark:text-gray-500">
{humanizeNumber(assets.length)}
<Camera className="w-4 h-4" />
</div>
)}
</div>
}
/>
<PhotoSelectionContext.Provider value={{ ...contextState, updateContext: contextState.updateContext }}>
{renderContent()}
{selectedAssets.length > 0 && (
<FloatingBar>
<div className="flex items-center gap-2 justify-between w-full">
<p className="text-sm text-muted-foreground">
{contextState.selectedIds.length} Selected
</p>
<div className="flex items-center gap-2">
{contextState.selectedIds.length === contextState.assets.length ? (
<Button variant="outline" size="sm" onClick={() => contextState.updateContext({ selectedIds: [] })}>
Unselect all
</Button>
) : (
<Button variant="outline" size="sm" onClick={() => contextState.updateContext({ selectedIds: contextState.assets.map((a) => a.id) })}>
Select all
</Button>
)}
<div className="h-[10px] w-[1px] bg-zinc-500 dark:bg-zinc-600" />
<AlbumSelectorDialog
onSelected={handleAddToAlbum}
onSubmit={handleCreateAlbumWithAssets}
/>
<div className="h-[10px] w-[1px] bg-zinc-500 dark:bg-zinc-600" />
<AlertDialog
title="Move selected assets to Trash?"
description="This action will move the selected assets to trash. You can restore them later."
onConfirm={handleTrash}
disabled={contextState.selectedIds.length === 0}
>
<Button variant="outline" size="sm" disabled={contextState.selectedIds.length === 0}>
<Trash className="w-4 h-4 mr-2" />
Trash
</Button>
</AlertDialog>
<AlertDialog
title="Delete the selected assets?"
description="This action will delete the selected assets and cannot be undone."
onConfirm={handleDelete}
disabled={contextState.selectedIds.length === 0}
>
<Button variant="destructive" size="sm" disabled={contextState.selectedIds.length === 0}>
<Trash2 className="w-4 h-4 mr-2" />
Delete
</Button>
</AlertDialog>
</div>
</div>
</FloatingBar>
)}
</PhotoSelectionContext.Provider>
</PageLayout>
)
}
```
**Step 2: Commit**
```bash
git add src/pages/assets/orphan-finder.tsx
git commit -m "feat: add orphan finder page with filters and bulk actions"
```
---
### Task 4: Add sidebar entry
**Files:**
- Modify: `src/config/constants/sidebarNavs.tsx`
**Step 1: Add the sidebar nav entry**
Add `PackageSearch` to the lucide-react import, then add the entry after "Bulk Duplicate Finder":
```tsx
{
title: "Orphan Finder",
link: "/assets/orphan-finder",
icon: <PackageSearch className="h-4 w-4" />,
},
```
**Step 2: Commit**
```bash
git add src/config/constants/sidebarNavs.tsx
git commit -m "feat: add orphan finder to sidebar navigation"
```
---
### Task 5: Verify createAlbumWithAssets handler exists
**Files:**
- Possibly modify: `src/handlers/api/album.handler.ts`
**Step 1: Check if `createAlbumWithAssets` exists in album handler**
If it doesn't exist, add it. This function should create an album via Immich API and then add selected assets to it.
```typescript
export const createAlbumWithAssets = async (albumName: string, assetIds: string[]) => {
const album = await API.post(CREATE_ALBUM_PATH, { albumName, assetIds });
return album;
}
```
**Step 2: Commit if changes were needed**
```bash
git add src/handlers/api/album.handler.ts
git commit -m "feat: add createAlbumWithAssets handler"
```
---
### Task 6: Manual testing and fixes
**Step 1: Run the dev server**
```bash
bun run dev
```
**Step 2: Test each filter combination**
- Visit `/assets/orphan-finder`
- Toggle each checkbox individually, verify results
- Combine filters, verify AND behavior
- Test asset type dropdown
- Select assets, verify floating bar appears
- Test "Add to Album" flow
- Test Trash and Delete flows
- Verify sidebar link works
**Step 3: Fix any issues found and commit**
```bash
git add -A
git commit -m "fix: orphan finder polish and bug fixes"
```