refactor: migrate reference widget related function to Typescript

Signed-off-by: Ferdinand Thiessen <opensource@fthiessen.de>

Author: susnux

src/components/NcRichText/NcReferencePicker/NcCustomPickerElement.vue

@@ -8,7 +8,11 @@
 </template>
 
 <script>
-import { renderCustomPickerElement, isCustomPickerElementRegistered, destroyCustomPickerElement } from './../../../functions/reference/customPickerElements.js'
+import {
+	renderCustomPickerElement,
+	isCustomPickerElementRegistered,
+	destroyCustomPickerElement,
+} from '../../../functions/reference/customPickerElements.ts'
 
 export default {
 	name: 'NcCustomPickerElement',

src/components/NcRichText/NcReferencePicker/NcProviderList.vue

@@ -42,7 +42,7 @@
 </template>
 
 <script>
-import { searchProvider } from './../../../functions/reference/providerHelper.js'
+import { searchProvider } from '../../../functions/reference/providerHelper.ts'
 import { isUrl } from './utils.js'
 import NcEmptyContent from '../../NcEmptyContent/index.ts'
 import NcHighlight from '../../NcHighlight/index.ts'

src/components/NcRichText/NcReferencePicker/NcReferencePicker.vue

@@ -38,8 +38,8 @@ import NcCustomPickerElement from './NcCustomPickerElement.vue'
 import NcProviderList from './NcProviderList.vue'
 import NcRawLinkInput from './NcRawLinkInput.vue'
 import NcSearch from './NcSearch.vue'
-import { isCustomPickerElementRegistered } from './../../../functions/reference/customPickerElements.js'
-import { touchProvider } from './../../../functions/reference/providerHelper.js'
+import { isCustomPickerElementRegistered } from '../../../functions/reference/customPickerElements.ts'
+import { touchProvider } from '../../../functions/reference/providerHelper.ts'
 
 const MODES = {
 	providerList: 1,

src/components/NcRichText/NcReferencePicker/NcReferencePickerModal.vue

@@ -43,7 +43,7 @@
 
 <script>
 import NcReferencePicker from './NcReferencePicker.vue'
-import { getCustomPickerElementSize, isCustomPickerElementRegistered } from './../../../functions/reference/customPickerElements.js'
+import { getCustomPickerElementSize, isCustomPickerElementRegistered } from '../../../functions/reference/customPickerElements.ts'
 import NcButton from '../../NcButton/index.ts'
 import NcModal from '../../NcModal/index.js'
 import { t } from '../../../l10n.js'

src/components/NcRichText/index.js

@@ -11,20 +11,20 @@ import NcReferenceWidget from './NcReferenceWidget.vue'
 import NcReferencePicker from './NcReferencePicker/NcReferencePicker.vue'
 import NcReferencePickerModal from './NcReferencePicker/NcReferencePickerModal.vue'
 import NcSearch from './NcReferencePicker/NcSearch.vue'
-import { getLinkWithPicker } from './../../functions/reference/referencePickerModal.js'
+import { getLinkWithPicker } from '../../functions/reference/referencePickerModal.ts'
 import {
 	getProvider,
 	getProviders,
 	sortProviders,
 	searchProvider,
 	anyLinkProviderId,
-} from '../../functions/reference/providerHelper.js'
+} from '../../functions/reference/providerHelper.ts'
 import {
 	registerCustomPickerElement,
 	renderCustomPickerElement,
 	isCustomPickerElementRegistered,
 	NcCustomPickerRenderResult,
-} from '../../functions/reference/customPickerElements.js'
+} from '../../functions/reference/customPickerElements.ts'
 
 export default NcRichText
 

src/functions/reference/customPickerElements.ts

@@ -3,42 +3,79 @@
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
-if (!window._vue_richtext_custom_picker_elements) {
-	window._vue_richtext_custom_picker_elements = {}
-}
+import logger from '../../utils/logger'
+
+window._vue_richtext_custom_picker_elements ??= {}
+window._registerCustomPickerElement ??= registerCustomPickerElement
 
 /**
  * Representation of the render callback result
  * It contains a dom element and an object (Vue instance or other fancy things)
  */
-class NcCustomPickerRenderResult {
+export class NcCustomPickerRenderResult {
+
+	public element: HTMLElement
+	public object: object
 
 	/**
-	 * @param {HTMLElement} element The HTML element
-	 * @param {object} object The object
+	 * @param element - The HTML element
+	 * @param object - The object
 	 */
-	constructor(element, object) {
+	constructor(element: HTMLElement, object: object) {
 		this.element = element
 		this.object = object
 	}
 
 }
 
-const isCustomPickerElementRegistered = (id) => {
+interface CustomPickerElementProps {
+	providerId: number
+	accessible: boolean
+}
+
+type CustomPickerElementRegistrationCallback = (el: HTMLElement, options: CustomPickerElementProps) => void
+type CustomPickerElementDestroyCallback = (el: HTMLElement, result: NcCustomPickerRenderResult) => void
+
+export interface CustomPickerElement {
+	id: string
+	size: 'small' | 'normal' | 'large' | 'full'
+
+	callback: CustomPickerElementRegistrationCallback
+	onDestroy: CustomPickerElementDestroyCallback
+}
+
+/**
+ * @param id - Id of the element to check
+ */
+export function isCustomPickerElementRegistered(id: string): boolean {
 	return !!window._vue_richtext_custom_picker_elements[id]
 }
 
-const getCustomPickerElementSize = (id) => {
+/**
+ * @param id - Id of the element to get
+ */
+export function getCustomPickerElementSize(id: string): 'small' | 'normal' | 'large' | 'full' | null {
 	const size = window._vue_richtext_custom_picker_elements[id]?.size
 	if (['small', 'normal', 'large', 'full'].includes(size)) {
 		return size
 	}
 	return null
 }
 
-const registerCustomPickerElement = (id, callback, onDestroy = (el) => {}, size = 'large') => {
+/**
+ * @param id - Id of element to register
+ * @param callback - Render callback
+ * @param onDestroy - Cleanup callback
+ * @param size - Size of the element
+ */
+export function registerCustomPickerElement(
+	id: string,
+	callback: CustomPickerElementRegistrationCallback,
+	onDestroy: CustomPickerElementDestroyCallback = () => {},
+	size: CustomPickerElement['size'] = 'large',
+) {
 	if (window._vue_richtext_custom_picker_elements[id]) {
-		console.error('Custom reference picker element for id ' + id + ' already registered')
+		logger.error(`Custom reference picker element for id ${id} already registered`)
 		return
 	}
 
@@ -50,30 +87,31 @@ const registerCustomPickerElement = (id, callback, onDestroy = (el) => {}, size
 	}
 }
 
-const renderCustomPickerElement = (el, { providerId, accessible }) => {
+/**
+ * @param el - element to render to
+ * @param options - Element options
+ */
+export function renderCustomPickerElement(el: HTMLElement, options: CustomPickerElementProps) {
+	const { providerId, accessible } = options
 	if (!window._vue_richtext_custom_picker_elements[providerId]) {
-		console.error('Custom reference picker element for reference provider ID ' + providerId + ' not registered')
+		logger.error(`Custom reference picker element for reference provider ID ${providerId} not registered`)
 		return
 	}
 
-	return window._vue_richtext_custom_picker_elements[providerId].callback(el, { providerId, accessible })
+	return window._vue_richtext_custom_picker_elements[providerId]
+		.callback(el, { providerId, accessible })
 }
 
-const destroyCustomPickerElement = (providerId, el, renderResult) => {
+/**
+ * @param providerId - Provider id of element to destroy
+ * @param el - The element to destroy element from
+ * @param renderResult - The render result
+ */
+export function destroyCustomPickerElement(providerId: string, el: HTMLElement, renderResult: NcCustomPickerRenderResult) {
 	if (!window._vue_richtext_custom_picker_elements[providerId]) {
 		return
 	}
 
-	window._vue_richtext_custom_picker_elements[providerId].onDestroy(el, renderResult)
-}
-
-window._registerCustomPickerElement = registerCustomPickerElement
-
-export {
-	NcCustomPickerRenderResult,
-	registerCustomPickerElement,
-	renderCustomPickerElement,
-	destroyCustomPickerElement,
-	isCustomPickerElementRegistered,
-	getCustomPickerElementSize,
+	window._vue_richtext_custom_picker_elements[providerId]
+		.onDestroy(el, renderResult)
 }

src/functions/reference/index.ts

@@ -3,36 +3,32 @@
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
-import { registerWidget, renderWidget, isWidgetRegistered, hasInteractiveView } from './widgets.ts'
-import { getLinkWithPicker } from './referencePickerModal.js'
-import {
-	getProvider,
-	getProviders,
-	sortProviders,
-	searchProvider,
-	anyLinkProviderId,
-} from './providerHelper.js'
-import {
-	registerCustomPickerElement,
-	renderCustomPickerElement,
-	isCustomPickerElementRegistered,
-	NcCustomPickerRenderResult,
-} from './customPickerElements.js'
-
 export {
+	type ReferenceWidgetProps,
+	type ReferenceWidgetRenderProperties,
+
 	registerWidget,
 	renderWidget,
 	isWidgetRegistered,
 	hasInteractiveView,
+} from './widgets.ts'
+
+export { getLinkWithPicker } from './referencePickerModal.ts'
+
+export {
+	type ReferenceProvider,
 
-	NcCustomPickerRenderResult,
-	registerCustomPickerElement,
-	renderCustomPickerElement,
-	isCustomPickerElementRegistered,
-	getLinkWithPicker,
-	anyLinkProviderId,
 	getProvider,
 	getProviders,
 	sortProviders,
 	searchProvider,
-}
+	anyLinkProviderId,
+} from './providerHelper.ts'
+
+export {
+	type CustomPickerElement,
+	registerCustomPickerElement,
+	renderCustomPickerElement,
+	isCustomPickerElementRegistered,
+	NcCustomPickerRenderResult,
+} from './customPickerElements.ts'

src/functions/reference/providerHelper.ts

@@ -10,45 +10,51 @@ import { t } from '../../l10n.js'
 import axios from '@nextcloud/axios'
 import { loadState } from '@nextcloud/initial-state'
 import { generateOcsUrl, imagePath } from '@nextcloud/router'
+import logger from '../../utils/logger.js'
+
+export interface ReferenceProvider {
+	id: string
+	title: string
+	icon_url: string
+	order: number
+	search_providers_ids?: string[]
+}
 
 export const anyLinkProviderId = 'any-link'
 
-const anyLinkProvider = {
+const anyLinkProvider: ReferenceProvider = {
 	id: anyLinkProviderId,
 	title: t('Any link'),
+	order: 0,
 	icon_url: imagePath('core', 'filetypes/link.svg'),
 }
 
 // only get the provider list once, even if functions of this file are imported multiple times by different apps/components
-if (!window._vue_richtext_reference_providers) {
-	window._vue_richtext_reference_providers = loadState('core', 'reference-provider-list', [])
-}
-
+window._vue_richtext_reference_providers ??= loadState('core', 'reference-provider-list', [])
 // single timestamps object used by every entity in the page
-if (!window._vue_richtext_reference_provider_timestamps) {
-	window._vue_richtext_reference_provider_timestamps = loadState('core', 'reference-provider-timestamps', {})
-}
+window._vue_richtext_reference_provider_timestamps ??= loadState('core', 'reference-provider-timestamps', {})
 
 /**
- * @param {string} providerId The provider ID
- * @return {object} The provider object
+ * @param providerId - The provider ID
+ * @return The provider object
  */
-export function getProvider(providerId) {
+export function getProvider(providerId: string): ReferenceProvider|undefined {
 	if (providerId === anyLinkProviderId) {
 		return anyLinkProvider
 	}
+
 	return getProviders().find(p => p.id === providerId)
 }
 
 /**
- * @return {Array} Raw provider list as it was provided by the server
+ * Get raw provider list as it was provided by the server
  */
-export function getProviders() {
-	return window._vue_richtext_reference_providers.filter(p => {
+export function getProviders(): ReferenceProvider[] {
+	return window._vue_richtext_reference_providers.filter((p) => {
 		// avoid providers with no associated search provider and no custom component registered
 		const keep = (!!p.search_providers_ids && p.search_providers_ids.length > 0) || isCustomPickerElementRegistered(p.id)
 		if (!keep) {
-			console.debug('[smart picker]', p.id, 'reference provider is discoverable but does not have any related search provider or custom picker component registered')
+			logger.debug(`[smart picker] ${p.id} reference provider is discoverable but does not have any related search provider or custom picker component registered`)
 		}
 		return keep
 	})
@@ -59,10 +65,10 @@ export function getProviders() {
  * - their "last used timestamp"
  * - their "order" property (coming from the provider declaration in the server implementation)
  *
- * @param {Array} providerList list of provider objects
- * @return {Array} the sorted provider list
+ * @param providerList - List of provider objects
+ * @return The sorted provider list
  */
-export function sortProviders(providerList) {
+export function sortProviders(providerList: ReferenceProvider[]): ReferenceProvider[] {
 	const timestamps = window._vue_richtext_reference_provider_timestamps
 
 	return providerList.sort((a, b) => {
@@ -90,21 +96,23 @@ export function sortProviders(providerList) {
  * Helper function to search a provider from a search query
  * Result is a sorted list of providers
  *
- * @param {string} query The search query
- * @param {number} limit (optional) max number of results
- * @return {Array} the sorted/filtered provider list
+ * @param query - The search query
+ * @param limit - (optional) max number of results
+ * @return The sorted/filtered provider list
  */
-export function searchProvider(query, limit = null) {
+export function searchProvider(query: string, limit?: number): ReferenceProvider[] {
 	const providers = getProviders()
 	const escapedQuery = query.replace(/[/\-\\^$*+?.()|[\]{}]/g, '\\$&')
 	const regexp = new RegExp(escapedQuery, 'i')
 	const sortedProviders = sortProviders(providers)
-	const filteredSortedProviders = sortedProviders.filter(p => {
+	const filteredSortedProviders = sortedProviders.filter((p) => {
 		return p.title.match(regexp)
 	})
+
 	const searchResult = limit
 		? filteredSortedProviders.slice(0, limit)
 		: filteredSortedProviders
+
 	// append the 'any link' provider in the full list or when there is no result
 	if (query === '' || searchResult.length === 0) {
 		searchResult.push(anyLinkProvider)
@@ -115,16 +123,12 @@ export function searchProvider(query, limit = null) {
 /**
  * Update the "last used timestamp" on the server side and then locally in the frontend
  *
- * @param {number} providerId The id of the search provider
+ * @param providerId - The id of the search provider
  */
-export function touchProvider(providerId) {
+export async function touchProvider(providerId: number) {
 	const timestamp = Math.floor(Date.now() / 1000)
-	const params = {
-		timestamp,
-	}
 	const url = generateOcsUrl('references/provider/{providerId}', { providerId })
-	axios.put(url, params)
-		.then((response) => {
-			window._vue_richtext_reference_provider_timestamps[providerId] = timestamp
-		})
+
+	await axios.put(url, { timestamp })
+	window._vue_richtext_reference_provider_timestamps[providerId] = timestamp
 }