Merge pull request #8532 from nextcloud-libraries/feat/reference_picker_return_object

feat(referencePicker): introduce getReferenceWithPicker()

Author: ShGKme

src/components/NcRichText/NcReferencePicker/NcCustomPickerElement.vue

@@ -29,6 +29,7 @@ export default {
 	emits: [
 		'cancel',
 		'submit',
+		'pick',
 	],
 
 	data() {
@@ -62,11 +63,15 @@ export default {
 				this.renderResult = result
 				if (this.renderResult.object?._isVue && this.renderResult.object?.$on) {
 					this.renderResult.object.$on('submit', this.onSubmit)
+					this.renderResult.object.$on('pick', this.onPick)
 					this.renderResult.object.$on('cancel', this.onCancel)
 				}
 				this.renderResult.element.addEventListener('submit', (e) => {
 					this.onSubmit(e.detail)
 				})
+				this.renderResult.element.addEventListener('pick', (e) => {
+					this.onPick(e.detail)
+				})
 				this.renderResult.element.addEventListener('cancel', this.onCancel)
 			})
 		},
@@ -75,6 +80,10 @@ export default {
 			this.$emit('submit', value)
 		},
 
+		onPick(value) {
+			this.$emit('pick', value)
+		},
+
 		onCancel() {
 			this.$emit('cancel')
 		},

src/components/NcRichText/NcReferencePicker/NcProviderList.vue

@@ -65,6 +65,7 @@ export default {
 	emits: [
 		'selectProvider',
 		'submit',
+		'pick',
 	],
 
 	data() {
@@ -102,6 +103,7 @@ export default {
 			if (p !== null) {
 				if (p.isLink) {
 					this.$emit('submit', p.title)
+					this.$emit('pick', { link: p.title })
 				} else {
 					this.$emit('selectProvider', p)
 				}

src/components/NcRichText/NcReferencePicker/NcRawLinkInput.vue

@@ -71,6 +71,7 @@ export default {
 
 	emits: [
 		'submit',
+		'pick',
 	],
 
 	data() {
@@ -102,6 +103,7 @@ export default {
 			const value = e.target.value
 			if (this.isLinkValid) {
 				this.$emit('submit', value)
+				this.$emit('pick', { link: value })
 			}
 		},
 

src/components/NcRichText/NcReferencePicker/NcReferencePicker.vue

@@ -14,26 +14,30 @@
 			ref="provider-list"
 			@selectProvider="onProviderSelected"
 			@submit="submitLink"
+			@pick="pickLink"
 			@cancel="cancelProviderSelection" />
 		<NcRawLinkInput
 			v-else-if="mode === MODES.standardLinkInput"
 			ref="url-input"
 			:provider="selectedProvider"
 			@submit="submitLink"
+			@pick="pickLink"
 			@cancel="cancelRawLinkInput" />
 		<NcSearch
 			v-else-if="mode === MODES.searchInput"
 			ref="url-input"
 			:provider="selectedProvider"
-			@cancel="cancelSearch"
-			@submit="submitLink" />
+			@submit="submitLink"
+			@pick="pickLink"
+			@cancel="cancelSearch" />
 		<div
 			v-else-if="mode === MODES.customElement"
 			class="custom-element-wrapper">
 			<NcCustomPickerElement
 				:provider="selectedProvider"
 				class="custom-element"
 				@submit="submitLink"
+				@pick="pickLink"
 				@cancel="cancelCustomElement" />
 		</div>
 	</div>
@@ -97,6 +101,7 @@ export default {
 		'cancelSearch',
 		'providerSelected',
 		'submit',
+		'pick',
 	],
 
 	data() {
@@ -181,6 +186,14 @@ export default {
 			this.deselectProvider()
 		},
 
+		pickLink(reference) {
+			if (this.selectedProvider !== null) {
+				touchProvider(this.selectedProvider.id)
+			}
+			this.$emit('pick', reference)
+			this.deselectProvider()
+		},
+
 		deselectProvider() {
 			this.selectedProvider = null
 			this.$emit('providerSelected', null)

src/components/NcRichText/NcReferencePicker/NcReferencePickerModal.vue

@@ -41,6 +41,7 @@
 				:focusOnCreate="focusOnCreate"
 				@providerSelected="onProviderSelect"
 				@submit="onSubmit"
+				@pick="onPick"
 				@cancel="onCancel" />
 		</div>
 	</NcModal>
@@ -96,6 +97,7 @@ export default {
 	emits: [
 		'cancel',
 		'submit',
+		'pick',
 	],
 
 	data() {
@@ -152,6 +154,11 @@ export default {
 			this.$emit('submit', value)
 		},
 
+		onPick(value) {
+			this.show = false
+			this.$emit('pick', value)
+		},
+
 		onProviderSelect(provider) {
 			this.selectedProvider = provider
 			// provider was deselected and we started with an inital one: just close the modal

src/components/NcRichText/NcReferencePicker/NcSearch.vue

@@ -122,6 +122,7 @@ export default {
 
 	emits: [
 		'submit',
+		'pick',
 	],
 
 	data() {
@@ -248,6 +249,11 @@ export default {
 				if (item.resourceUrl) {
 					this.cancelSearchRequests()
 					this.$emit('submit', item.resourceUrl)
+					const reference = { link: item.resourceUrl }
+					if (item.title) {
+						reference.title = item.title
+					}
+					this.$emit('pick', reference)
 				} else if (item.isMore) {
 					this.searchMoreOf(item.providerId).then(() => {
 						// allow clicking twice on the same "more" item

src/components/NcRichText/index.ts

@@ -22,7 +22,7 @@ import {
 	searchProvider,
 	sortProviders,
 } from '../../functions/reference/providerHelper.ts'
-import { getLinkWithPicker } from '../../functions/reference/referencePickerModal.ts'
+import { getLinkWithPicker, getReferenceWithPicker } from '../../functions/reference/referencePickerModal.ts'
 import { isWidgetRegistered, registerWidget, renderWidget } from './../../functions/reference/widgets.ts'
 
 export default NcRichText
@@ -32,6 +32,7 @@ export {
 	getLinkWithPicker,
 	getProvider,
 	getProviders,
+	getReferenceWithPicker,
 	isCustomPickerElementRegistered,
 	isWidgetRegistered,
 	NcCustomPickerRenderResult,

src/functions/reference/index.ts

@@ -13,7 +13,10 @@ export {
 	renderWidget,
 } from './widgets.ts'
 
-export { getLinkWithPicker } from './referencePickerModal.ts'
+export {
+	getLinkWithPicker,
+	getReferenceWithPicker,
+} from './referencePickerModal.ts'
 
 export {
 	type ReferenceProvider,

src/functions/reference/referencePickerModal.ts

@@ -8,7 +8,7 @@ import NcReferencePickerModal from './../../components/NcRichText/NcReferencePic
 import { getProvider } from './providerHelper.js'
 
 /**
- * Creates a reference picker modal and return a promise which provides the result
+ * Creates a reference picker modal and return a promise which provides the link URL
  *
  * @param providerId - Optional ID of initial selected provider
  * @param isInsideViewer - Should be true if this function is called while the Viewer is displayed
@@ -37,3 +37,40 @@ export async function getLinkWithPicker(providerId?: string, isInsideViewer?: bo
 
 	return promise
 }
+
+/**
+ * Creates a reference picker modal and return a promise which provides the reference object.
+ *
+ * The function guarantees a `link: string` on the resolved object. Custom picker elements may
+ * include additional fields (e.g. `title`).
+ *
+ * @experimental The shape of the resolved reference and the signature of this function may still change.
+ *
+ * @template T - Expected shape of the resolved reference, must include `link: string`
+ * @param providerId - Optional ID of initial selected provider
+ * @param isInsideViewer - Should be true if this function is called while the Viewer is displayed
+ */
+export async function getReferenceWithPicker<T extends { link: string }>(providerId?: string, isInsideViewer?: boolean): Promise<T> {
+	const modalId = 'referencePickerModal'
+	const modalElement = document.createElement('div')
+	modalElement.id = modalId
+	document.body.append(modalElement)
+
+	const { promise, reject, resolve } = Promise.withResolvers<T>()
+	const initialProvider = (providerId && getProvider(providerId)) || null
+	const view = createApp(NcReferencePickerModal, {
+		initialProvider,
+		isInsideViewer,
+		onCancel() {
+			view.unmount()
+			reject(new Error('User cancellation'))
+		},
+		onPick(reference: T) {
+			view.unmount()
+			resolve(reference)
+		},
+	})
+	view.mount(modalElement)
+
+	return promise
+}