feat(core): add reactive adapter for the unified search controller

Signed-off-by: Peter Ringelmann <peter.ringelmann@nextcloud.com>

Author: pringelmann

core/src/composables/useUnifiedSearch.ts

@@ -0,0 +1,28 @@
+/*!
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+import { onUnmounted, shallowRef } from 'vue'
+import { UnifiedSearchController } from '../services/UnifiedSearchController.ts'
+
+/**
+ * Reactive adapter over UnifiedSearchController for use in an SFC.
+ */
+export function useUnifiedSearch() {
+	const searchStates = shallowRef({})
+
+	const controller = new UnifiedSearchController((states) => {
+		searchStates.value = states
+	})
+
+	onUnmounted(() => {
+		controller.dispose()
+	})
+
+	return {
+		searchStates,
+		search: controller.search.bind(controller),
+		loadMore: controller.loadMore.bind(controller),
+	}
+}

core/src/services/UnifiedSearchController.ts

@@ -37,6 +37,8 @@ export class UnifiedSearchController {
 	private revealTimer: ReturnType<typeof setTimeout> | null = null
 	private pendingCancels: (() => void)[] = []
 
+	constructor(private onChange?: (states: Record<string, CategorySearchState>) => void) {}
+
 	/**
 	 * Start a search. Cancels and replaces any search already in flight.
 	 *
@@ -67,12 +69,12 @@ export class UnifiedSearchController {
 	 */
 	async loadMore(category: string): Promise<void> {
 		const generation = this.searchGeneration
-		const categoryState = this.searchStates[category]
-		if (!categoryState || !categoryState.hasMore || categoryState.status !== 'loaded') {
+		const categoryState = { ...this.searchStates[category] }
+		if (!categoryState.hasMore || categoryState.status !== 'loaded') {
 			return
 		}
-		categoryState.status = 'loading'
-		categoryState.loadMoreFailed = false
+
+		this.patchStates({ [category]: { status: 'loading', loadMoreFailed: false } })
 
 		const { request, cancel } = unifiedSearch({
 			type: category,
@@ -89,17 +91,19 @@ export class UnifiedSearchController {
 				return
 			}
 			const { entries, cursor, hasMore } = response.data.ocs.data
-			categoryState.entries.push(...entries)
-			categoryState.cursor = cursor
-			categoryState.hasMore = hasMore
+
+			this.patchStates({[category]: {
+				entries: [...categoryState.entries, ...entries],
+				cursor,
+				hasMore,
+				status: 'loaded',
+			}})
 		} catch {
 			if (this.searchGeneration !== generation) {
 				return
 			}
-			categoryState.loadMoreFailed = true
+			this.patchStates({ [category]: { status: 'loaded', loadMoreFailed: true } })
 		}
-
-		categoryState.status = 'loaded'
 	}
 
 	/**
@@ -124,13 +128,14 @@ export class UnifiedSearchController {
 		generation: number,
 		categories: string[],
 	): Promise<void> {
-		this.searchStates[category] = {
+		this.patchStates({ [category]: {
 			status: 'loading',
 			entries: [],
 			cursor: null,
 			hasMore: false,
 			loadMoreFailed: false,
-		}
+		} })
+
 		const { request, cancel } = unifiedSearch({
 			type: category,
 			query: this.query,
@@ -148,24 +153,24 @@ export class UnifiedSearchController {
 			}
 
 			const { entries, cursor, hasMore } = response.data.ocs.data
-			this.searchStates[category] = {
+			this.patchStates({ [category]: {
 				status: 'loaded',
 				entries,
 				cursor,
 				hasMore,
 				loadMoreFailed: false,
-			}
+			} })
 		} catch {
 			if (this.searchGeneration !== generation) {
 				return
 			}
-			this.searchStates[category] = {
+			this.patchStates({ [category]: {
 				status: 'failed',
 				entries: [],
 				cursor: null,
 				hasMore: false,
 				loadMoreFailed: false,
-			}
+			}})
 		}
 
 		this.reconcileCategoryStatuses(categories)
@@ -176,7 +181,7 @@ export class UnifiedSearchController {
 			if (['loading', 'failed'].includes(this.searchStates[category].status)) {
 				return
 			}
-			this.searchStates[category].status = this.shouldBlockCategory(category, categories) ? 'blocked' : 'loaded'
+			this.patchStates({ [category]: { status: this.shouldBlockCategory(category, categories) ? 'blocked' : 'loaded' } })
 		})
 	}
 
@@ -207,7 +212,7 @@ export class UnifiedSearchController {
 	private unblockAllCategories(categories: string[]): void {
 		categories.forEach((category) => {
 			if (this.searchStates[category].status === 'blocked') {
-				this.searchStates[category].status = 'loaded'
+				this.patchStates({ [category]: { status: 'loaded' } })
 			}
 		})
 	}
@@ -222,4 +227,12 @@ export class UnifiedSearchController {
 			return categoryState && ['loading', 'blocked'].includes(categoryState.status)
 		})
 	}
+
+	private patchStates(next: Record<string, Partial<CategorySearchState>>): void {
+		Object.keys(next).forEach((category) => {
+			const categoryState = { ...this.searchStates[category], ...next[category] }
+			this.searchStates[category] = categoryState
+		})
+		this.onChange?.(this.getSnapshot())
+	}
 }

core/src/tests/composables/useUnifiedSearch.spec.ts

@@ -0,0 +1,136 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+import { mount } from '@vue/test-utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { defineComponent, h } from 'vue'
+
+const service = vi.hoisted(() => ({
+	search: vi.fn(),
+	getProviders: vi.fn(),
+	getContacts: vi.fn(),
+}))
+vi.mock('../../services/UnifiedSearchService.js', () => service)
+
+import { useUnifiedSearch } from '../../composables/useUnifiedSearch.ts'
+
+/**
+ * Deferred stand-in for a provider's `search()` return value. Resolve it to
+ * make that provider arrive on demand. Mirrors the controller spec's helper.
+ */
+function deferredProvider() {
+	const { promise, resolve, reject } = Promise.withResolvers<{ entries: unknown[] }>()
+	return {
+		cancel: vi.fn(),
+		request: async () => {
+			const { entries } = await promise
+			return { data: { ocs: { data: { entries } } } }
+		},
+		resolve: (entries: unknown[] = []) => resolve({ entries }),
+		reject,
+	}
+}
+
+/**
+ * Deferred stand-in that serves successive pages, for exercising loadMore.
+ */
+function pagedProvider() {
+	const pages: ReturnType<typeof Promise.withResolvers<{ entries: unknown[], cursor: string | null, hasMore: boolean }>>[] = []
+	const pageAt = (index: number) => (pages[index] ??= Promise.withResolvers())
+	let call = 0
+	return {
+		cancel: vi.fn(),
+		request: async () => {
+			const data = await pageAt(call++).promise
+			return { data: { ocs: { data } } }
+		},
+		resolvePage: (index: number, data: { entries: unknown[], cursor: string | null, hasMore: boolean }) => pageAt(index).resolve(data),
+	}
+}
+
+/**
+ * Register one deferred provider per category type on the mocked service.
+ */
+function mockProviders(types: string[]) {
+	const providers = Object.fromEntries(types.map((type) => [type, deferredProvider()]))
+	service.search.mockImplementation(({ type }: { type: string }) => providers[type])
+	return providers
+}
+
+/**
+ * Run the composable inside a real setup context (so onBeforeUnmount is wired)
+ * and hand the returned API plus the wrapper back to the test.
+ */
+function mountComposable() {
+	let api!: ReturnType<typeof useUnifiedSearch>
+	const wrapper = mount(defineComponent({
+		setup() {
+			api = useUnifiedSearch()
+			return () => h('div')
+		},
+	}))
+	return { wrapper, api }
+}
+
+beforeEach(() => {
+	vi.useFakeTimers()
+})
+
+afterEach(() => {
+	vi.clearAllMocks()
+	vi.useRealTimers()
+})
+
+describe('useUnifiedSearch', () => {
+	it('exposes an empty snapshot before any search', () => {
+		const { api } = mountComposable()
+
+		expect(api.searchStates.value).toEqual({})
+	})
+
+	it('reflects controller state reactively as a search resolves', async () => {
+		const providers = mockProviders(['files'])
+		const { api } = mountComposable()
+
+		api.search('query', ['files'])
+		providers.files.resolve(['a result'])
+		await vi.advanceTimersByTimeAsync(0)
+
+		expect(api.searchStates.value.files).toMatchObject({
+			status: 'loaded',
+			entries: ['a result'],
+		})
+	})
+
+	it('appends a page through loadMore and reflects it', async () => {
+		const files = pagedProvider()
+		service.search.mockReturnValue(files)
+		const { api } = mountComposable()
+
+		api.search('query', ['files'])
+		files.resolvePage(0, { entries: ['a'], cursor: 'cursor-1', hasMore: true })
+		await vi.advanceTimersByTimeAsync(0)
+
+		api.loadMore('files')
+		files.resolvePage(1, { entries: ['b'], cursor: 'cursor-2', hasMore: false })
+		await vi.advanceTimersByTimeAsync(0)
+
+		expect(api.searchStates.value.files).toMatchObject({
+			status: 'loaded',
+			entries: ['a', 'b'],
+			hasMore: false,
+		})
+	})
+
+	it('cancels in-flight requests when the component unmounts', () => {
+		const providers = mockProviders(['files'])
+		const { wrapper, api } = mountComposable()
+
+		api.search('query', ['files'])
+		wrapper.destroy()
+
+		// Unmount must dispose the controller, which cancels the pending request.
+		expect(providers.files.cancel).toHaveBeenCalledOnce()
+	})
+})