feat: toast timeout configuration

Signed-off-by: kristian-zendato <kristian.zendato@nextcloud.com>

Author: kristian-zendato

README.md

@@ -66,6 +66,12 @@ There are several options that can be passed in as a second parameter, like the
 showError('This is an error shown without a timeout', { timeout: -1 })
 ```
 
+Ordinary toasts (success, error, warning, info, and bare messages) use the user-configured toast timeout
+from the theming capabilities (`theming.toastTimeout`) when available, and fall back to
+`TOAST_DEFAULT_TIMEOUT` (7 seconds) otherwise.
+
+Loading toasts stay permanent until hidden manually, and undo toasts keep their fixed undo duration.
+
 A full list of available options can be found in the [documentation](https://nextcloud-libraries.github.io/nextcloud-dialogs/).
 
 ### FilePicker

lib/toast.spec.ts

@@ -14,9 +14,18 @@ import {
 	showSuccess,
 	showUndo,
 	showWarning,
+	TOAST_DEFAULT_TIMEOUT,
+	TOAST_PERMANENT_TIMEOUT,
 	ToastAriaLive,
+	ToastType,
 } from './toast.ts'
 
+const getCapabilities = vi.hoisted(() => vi.fn())
+
+vi.mock('@nextcloud/capabilities', () => ({
+	getCapabilities,
+}))
+
 /**
  * Wait for the 50 ms setTimeout used in announce() to fire.
  * We intentionally advance only 100 ms so the 7-second cleanup timers
@@ -445,3 +454,91 @@ describe('multiple toasts', () => {
 		expect(messages).toEqual(['First', 'Second', 'Third'])
 	})
 })
+
+describe('timeout resolution', () => {
+	beforeEach(() => {
+		getCapabilities.mockReset()
+	})
+
+	test('uses default timeout when capabilities are missing', async () => {
+		getCapabilities.mockReturnValue(undefined)
+		showMessage('hello')
+
+		await vi.advanceTimersByTimeAsync(TOAST_DEFAULT_TIMEOUT - 1)
+		expect(document.querySelector('[role="status"]')).not.toBeNull()
+
+		await vi.advanceTimersByTimeAsync(1)
+		expect(document.querySelector('[role="status"]')).toBeNull()
+	})
+
+	test('uses default timeout when capabilities access throws', async () => {
+		getCapabilities.mockImplementation(() => {
+			throw new Error('window is not defined')
+		})
+		showMessage('hello')
+
+		await vi.advanceTimersByTimeAsync(TOAST_DEFAULT_TIMEOUT - 1)
+		expect(document.querySelector('[role="status"]')).not.toBeNull()
+
+		await vi.advanceTimersByTimeAsync(1)
+		expect(document.querySelector('[role="status"]')).toBeNull()
+	})
+
+	test('uses toastTimeout from theming capabilities', async () => {
+		getCapabilities.mockReturnValue({
+			theming: {
+				toastTimeout: 15_000,
+			},
+		})
+		showMessage('hello')
+
+		await vi.advanceTimersByTimeAsync(14_999)
+		expect(document.querySelector('[role="status"]')).not.toBeNull()
+
+		await vi.advanceTimersByTimeAsync(1)
+		expect(document.querySelector('[role="status"]')).toBeNull()
+	})
+
+	test('allows permanent timeout from capabilities', async () => {
+		getCapabilities.mockReturnValue({
+			theming: {
+				toastTimeout: TOAST_PERMANENT_TIMEOUT,
+			},
+		})
+		showMessage('hello')
+
+		await vi.advanceTimersByTimeAsync(60_000)
+		expect(document.querySelector('[role="status"]')).not.toBeNull()
+	})
+
+	test('falls back for invalid capability values', async () => {
+		getCapabilities.mockReturnValue({
+			theming: {
+				toastTimeout: 0,
+			},
+		})
+		showMessage('hello')
+
+		await vi.advanceTimersByTimeAsync(TOAST_DEFAULT_TIMEOUT - 1)
+		expect(document.querySelector('[role="status"]')).not.toBeNull()
+
+		await vi.advanceTimersByTimeAsync(1)
+		expect(document.querySelector('[role="status"]')).toBeNull()
+	})
+
+	test('does not override loading toast duration', async () => {
+		getCapabilities.mockReturnValue({
+			theming: {
+				toastTimeout: 30_000,
+			},
+		})
+
+		showMessage('loading', {
+			type: ToastType.LOADING,
+			timeout: TOAST_PERMANENT_TIMEOUT,
+		})
+
+		await vi.advanceTimersByTimeAsync(60_000)
+		expect(document.querySelector('[role="status"]')).not.toBeNull()
+	})
+})

lib/toast.ts

@@ -3,6 +3,7 @@
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
+import { getCapabilities } from '@nextcloud/capabilities'
 import { createApp } from 'vue'
 import ToastContainer from './components/ToastContainer.vue'
 import ToastNotification from './components/ToastNotification.vue'
@@ -40,6 +41,38 @@ export const TOAST_DEFAULT_TIMEOUT = 7000
 /** Timeout value to show a toast permanently */
 export const TOAST_PERMANENT_TIMEOUT = -1
 
+type ThemingCapabilities = {
+	theming?: {
+		toastTimeout?: number
+	}
+}
+
+/**
+ * Whether a timeout value is valid for ordinary toasts.
+ *
+ * @param timeout Timeout in milliseconds
+ */
+function isValidToastTimeout(timeout: number): boolean {
+	return timeout === TOAST_PERMANENT_TIMEOUT || timeout > 0
+}
+
+/**
+ * Resolve the user-configured toast timeout from theming capabilities.
+ * Falls back to {@link TOAST_DEFAULT_TIMEOUT} when unset or invalid.
+ */
+function getToastTimeout(): number {
+	try {
+		const timeout = (getCapabilities() as ThemingCapabilities | undefined)?.theming?.toastTimeout
+		if (typeof timeout === 'number' && isValidToastTimeout(timeout)) {
+			return timeout
+		}
+	} catch (_error) {
+		// Catch any exception from capability access and fallback to default timeout.
+		console.error('Error getting toast timeout:', _error)
+	}
+	return TOAST_DEFAULT_TIMEOUT
+}
+
 export interface ToastOptions {
 	/**
 	 * Defines the timeout in milliseconds after which the toast is closed. Set to -1 to have a persistent toast.
@@ -246,7 +279,7 @@ function getAnnouncementText(data: string | Node, isHTML: boolean): string {
  */
 export function showMessage(data: string | Node, options?: ToastOptions): ToastHandle {
 	const opts = {
-		timeout: TOAST_DEFAULT_TIMEOUT,
+		timeout: getToastTimeout(),
 		isHTML: false,
 		type: undefined as ToastType | undefined,
 		selector: undefined as string | undefined,

package-lock.json

@@ -51,6 +51,7 @@
     "@nextcloud/auth": "^2.6.0",
     "@nextcloud/axios": "^2.6.0",
     "@nextcloud/browser-storage": "^0.5.0",
+    "@nextcloud/capabilities": "^1.2.1",
     "@nextcloud/event-bus": "^3.3.3",
     "@nextcloud/files": "^4.0.0",
     "@nextcloud/initial-state": "^3.0.0",