From 192f71a13cb8e43e24d293df362f5e38dab3b26b Mon Sep 17 00:00:00 2001
From: taoso <tao@zz.ac>
Date: Mon, 9 Mar 2026 03:45:04 +0800
Subject: [PATCH] feat: allow clearing background image (#1290)

Co-authored-by: Kyle Mendell <kmendell@ofkm.us>
Co-authored-by: Kyle Mendell <ksm@ofkm.us>
---
 .../controller/app_images_controller.go       | 16 ++++++
 .../src/lib/components/login-wrapper.svelte   | 53 ++++++++++++++-----
 .../src/lib/services/app-config-service.ts    |  5 ++
 .../application-configuration/+page.svelte    | 11 ++--
 .../update-application-images.svelte          |  9 ++--
 5 files changed, 74 insertions(+), 20 deletions(-)

diff --git a/backend/internal/controller/app_images_controller.go b/backend/internal/controller/app_images_controller.go
index 3e3c2b04..2230b6f0 100644
--- a/backend/internal/controller/app_images_controller.go
+++ b/backend/internal/controller/app_images_controller.go
@@ -36,6 +36,7 @@ func NewAppImagesController(
 	group.PUT("/application-images/favicon", authMiddleware.Add(), controller.updateFaviconHandler)
 	group.PUT("/application-images/default-profile-picture", authMiddleware.Add(), controller.updateDefaultProfilePicture)
 
+	group.DELETE("/application-images/background", authMiddleware.Add(), controller.deleteBackgroundImageHandler)
 	group.DELETE("/application-images/default-profile-picture", authMiddleware.Add(), controller.deleteDefaultProfilePicture)
 }
 
@@ -194,6 +195,21 @@ func (c *AppImagesController) updateBackgroundImageHandler(ctx *gin.Context) {
 	ctx.Status(http.StatusNoContent)
 }
 
+// deleteBackgroundImageHandler godoc
+// @Summary Delete background image
+// @Description Delete the application background image
+// @Tags Application Images
+// @Success 204 "No Content"
+// @Router /api/application-images/background [delete]
+func (c *AppImagesController) deleteBackgroundImageHandler(ctx *gin.Context) {
+	if err := c.appImagesService.DeleteImage(ctx.Request.Context(), "background"); err != nil {
+		_ = ctx.Error(err)
+		return
+	}
+
+	ctx.Status(http.StatusNoContent)
+}
+
 // updateFaviconHandler godoc
 // @Summary Update favicon
 // @Description Update the application favicon
diff --git a/frontend/src/lib/components/login-wrapper.svelte b/frontend/src/lib/components/login-wrapper.svelte
index 60683044..f8671866 100644
--- a/frontend/src/lib/components/login-wrapper.svelte
+++ b/frontend/src/lib/components/login-wrapper.svelte
@@ -1,3 +1,9 @@
+<script module lang="ts">
+	// Persist the last failing background image URL across route remounts so
+	// login pages without a background do not briefly retry the image and stutter.
+	let persistedMissingBackgroundImageUrl: string | undefined;
+</script>
+
 <script lang="ts">
 	import { afterNavigate } from '$app/navigation';
 	import { page } from '$app/state';
@@ -17,13 +23,32 @@
 		showAlternativeSignInMethodButton?: boolean;
 	} = $props();
 
+	let missingBackgroundImageUrl = $state<string | undefined>(persistedMissingBackgroundImageUrl);
+	let loadedBackgroundImageUrl = $state<string | undefined>();
 	let isInitialLoad = $state(false);
-	let animate = $derived(isInitialLoad && !$appConfigStore.disableAnimations);
+	let backgroundImageUrl = $derived(cachedBackgroundImage.getUrl());
+	let imageError = $derived(missingBackgroundImageUrl === backgroundImageUrl);
+	let imageLoaded = $derived(loadedBackgroundImageUrl === backgroundImageUrl);
+	let animate = $derived(isInitialLoad && imageLoaded && !$appConfigStore.disableAnimations);
 
 	afterNavigate((e) => {
 		isInitialLoad = !e?.from?.url;
 	});
 
+	function onBackgroundImageLoad() {
+		loadedBackgroundImageUrl = backgroundImageUrl;
+		if (persistedMissingBackgroundImageUrl === backgroundImageUrl) {
+			persistedMissingBackgroundImageUrl = undefined;
+			missingBackgroundImageUrl = undefined;
+		}
+	}
+
+	function onBackgroundImageError() {
+		loadedBackgroundImageUrl = undefined;
+		persistedMissingBackgroundImageUrl = backgroundImageUrl;
+		missingBackgroundImageUrl = backgroundImageUrl;
+	}
+
 	const isDesktop = new MediaQuery('min-width: 1024px');
 	let alternativeSignInButton = $state({
 		href: '/login/alternative',
@@ -46,9 +71,9 @@
 </script>
 
 {#if isDesktop.current}
-	<div class="h-screen items-center overflow-hidden text-center">
+	<div class="h-screen items-center overflow-hidden text-center flex justify-center">
 		<div
-			class="relative z-10 flex h-full w-[650px] 2xl:w-[800px] p-16 {cn(
+			class="flex h-full w-[650px] 2xl:w-[800px] p-16 {cn(
 				showAlternativeSignInMethodButton && 'pb-0'
 			)}"
 		>
@@ -69,16 +94,18 @@
 			</div>
 		</div>
 
-		<!-- Background image -->
-		<div class="absolute top-0 right-0 left-500px bottom-0 z-0 overflow-hidden rounded-[40px] m-6">
-			<img
-				src={cachedBackgroundImage.getUrl()}
-				class="{cn(
-					animate && 'animate-bg-zoom'
-				)} h-screen object-cover w-[calc(100vw-650px)] 2xl:w-[calc(100vw-800px)]"
-				alt={m.login_background()}
-			/>
-		</div>
+		{#if !imageError}
+			<!-- Background image -->
+			<div class="m-6 flex h-[calc(100vh-3rem)] overflow-hidden rounded-[40px]">
+				<img
+					src={backgroundImageUrl}
+					class="h-full object-cover {cn(animate && 'animate-bg-zoom')}"
+					alt={m.login_background()}
+					onload={onBackgroundImageLoad}
+					onerror={onBackgroundImageError}
+				/>
+			</div>
+		{/if}
 	</div>
 {:else}
 	<div
diff --git a/frontend/src/lib/services/app-config-service.ts b/frontend/src/lib/services/app-config-service.ts
index f73e7056..62e715a9 100644
--- a/frontend/src/lib/services/app-config-service.ts
+++ b/frontend/src/lib/services/app-config-service.ts
@@ -71,6 +71,11 @@ export default class AppConfigService extends APIService {
 		cachedBackgroundImage.bustCache();
 	};
 
+	deleteBackgroundImage = async () => {
+		await this.api.delete(`/application-images/background`);
+		cachedBackgroundImage.bustCache();
+	};
+
 	deleteDefaultProfilePicture = async () => {
 		await this.api.delete('/application-images/default-profile-picture');
 		cachedDefaultProfilePicture.bustCache();
diff --git a/frontend/src/routes/settings/admin/application-configuration/+page.svelte b/frontend/src/routes/settings/admin/application-configuration/+page.svelte
index a2244e70..c4c592ba 100644
--- a/frontend/src/routes/settings/admin/application-configuration/+page.svelte
+++ b/frontend/src/routes/settings/admin/application-configuration/+page.svelte
@@ -44,7 +44,7 @@
 		logoDark: File | undefined,
 		logoEmail: File | undefined,
 		defaultProfilePicture: File | null | undefined,
-		backgroundImage: File | undefined,
+		backgroundImage: File | null | undefined,
 		favicon: File | undefined
 	) {
 		const faviconPromise = favicon ? appConfigService.updateFavicon(favicon) : Promise.resolve();
@@ -68,9 +68,12 @@
 					? appConfigService.updateDefaultProfilePicture(defaultProfilePicture)
 					: Promise.resolve();
 
-		const backgroundImagePromise = backgroundImage
-			? appConfigService.updateBackgroundImage(backgroundImage)
-			: Promise.resolve();
+		const backgroundImagePromise =
+			backgroundImage === null
+			? appConfigService.deleteBackgroundImage()
+			: backgroundImage
+				? appConfigService.updateBackgroundImage(backgroundImage)
+				: Promise.resolve();
 
 		await Promise.all([
 			lightLogoPromise,
diff --git a/frontend/src/routes/settings/admin/application-configuration/update-application-images.svelte b/frontend/src/routes/settings/admin/application-configuration/update-application-images.svelte
index 5efdca8c..df8e8a94 100644
--- a/frontend/src/routes/settings/admin/application-configuration/update-application-images.svelte
+++ b/frontend/src/routes/settings/admin/application-configuration/update-application-images.svelte
@@ -17,7 +17,7 @@
 			logoDark: File | undefined,
 			logoEmail: File | undefined,
 			defaultProfilePicture: File | null | undefined,
-			backgroundImage: File | undefined,
+			backgroundImage: File | null | undefined,
 			favicon: File | undefined
 		) => void;
 	} = $props();
@@ -26,10 +26,11 @@
 	let logoDark = $state<File | undefined>();
 	let logoEmail = $state<File | undefined>();
 	let defaultProfilePicture = $state<File | null | undefined>();
-	let backgroundImage = $state<File | undefined>();
+	let backgroundImage = $state<File | null | undefined>();
 	let favicon = $state<File | undefined>();
 
 	let defaultProfilePictureSet = $state(true);
+	let backgroundImageSet = $state(true);
 </script>
 
 <div class="flex flex-col gap-8">
@@ -77,10 +78,12 @@
 	/>
 	<ApplicationImage
 		id="background-image"
-		imageClass="h-[350px] max-w-[500px]"
+		imageClass="max-h-[350px] max-w-[500px]"
 		label={m.background_image()}
+		isResetable
 		bind:image={backgroundImage}
 		imageURL={cachedBackgroundImage.getUrl()}
+		isImageSet={backgroundImageSet}
 	/>
 </div>
 <div class="flex justify-end">