Merge pull request #6195 from nextcloud-libraries/feat/add-spawn-dialog

docs/functions/spawnDialog.md

@@ -0,0 +1,107 @@
+<!--
+ - SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ - SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+```ts static
+import {
+	spawnDialog,
+} from '@nextcloud/vue/dist/Functions/dialog.js'
+```
+
+## Definitions
+
+```ts static
+/**
+ * Helper to spawn a Vue dialog without having to mount it from a component
+ *
+ * @param dialog The dialog component to spawn - the component must emit the 'close' event whenever it is closed
+ * @param props Properties to pass to the dialog
+ * @param props.container Optionally pass a query selector for the dialog container element
+ * @param onClose Callback when the dialog is closed (parameters of the 'close' event of the dialog)
+ */
+function spawnDialog(
+	dialog: Component | AsyncComponent,
+	props: Record<string, unknown>,
+	onClose: (...rest: unknown[]) => void = () => {},
+): Vue;
+```
+
+## Usage
+
+The main use case is to be able to spawn a dialog from code, without the need of including the dialog component in the template.
+So a Vue dialog can be spawned in any context and not just from Vue components but also from callback functions or other API.
+
+```vue
+<template>
+	<div>
+		<NcButton @click="onSpawnDialog">🖱 click to spawn a dialog</NcButton>
+	</div>
+</template>
+
+<script>
+// Example dialog component that would be normally imported
+// Important: The dialog must emit a 'close' event whenever it is closed
+const ExampleDialog = {
+	template: `
+		<NcDialog :buttons="buttons"
+			name="Spawned dialog"
+			message="This dialog was spawned using the 'spawnDialog' function."
+			@closing="saveResult"
+			@update:open="onClose" />`,
+	props: {
+		timesClicked: {
+			type: Number,
+			required: true,
+		},
+	},
+	data() {
+		return {
+			result: null,
+		}
+	},
+	computed: {
+		buttons() {
+			return [
+				{
+					label: 'Cancel',
+					callback: () => 'cancelled',
+				},
+				{
+					label: 'Accept',
+					type: 'primary',
+					callback: () => 'accepted',
+				},
+			]
+		}
+	},
+	methods: {
+		saveResult(result) {
+			this.result = result
+		},
+		onClose() {
+			this.$emit('close', this.result)
+		},
+	}
+}
+
+export default {
+	data() {
+		return {
+			timesClicked: 0,
+		}
+	},
+	methods: {
+		onSpawnDialog() {
+			this.timesClicked += 1
+			spawnDialog(
+				ExampleDialog,
+				{
+					timesClicked: this.timesClicked,
+				},
+				(result) => window.alert(`Dialog was ${result}`)
+			)
+		},
+	},
+}
+</script>
+```

src/functions/dialog/index.ts

@@ -0,0 +1,50 @@
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+import type { AsyncComponent, Component } from 'vue'
+
+import Vue, { toRaw } from 'vue'
+
+interface DialogProps {
+	[index: string]: unknown
+	container?: string
+}
+
+/**
+ * Helper to spawn a Vue dialog without having to mount it from a component
+ *
+ * @param dialog The dialog component to spawn
+ * @param props Properties to pass to the dialog
+ * @param props.container Optionally pass a query selector for the dialog container element
+ * @param onClose Callback when the dialog is closed
+ */
+export function spawnDialog(
+	dialog: Component | AsyncComponent,
+	props?: DialogProps,
+	onClose: (...rest: unknown[]) => void = () => {},
+): Vue {
+	const el = document.createElement('div')
+
+	const container: HTMLElement = typeof props?.container === 'string'
+		? (document.querySelector(props.container) || document.body)
+		: document.body
+	container.appendChild(el)
+
+	const vm = new Vue({
+		el,
+		name: 'VueDialogHelper',
+		render: (h) =>
+			h(dialog, {
+				props,
+				on: {
+					close: (...rest: unknown[]) => {
+						onClose(...rest.map(v => toRaw(v)))
+						vm.$destroy()
+						el.remove()
+					},
+				},
+			}),
+	})
+	return vm
+}

src/functions/index.js → src/functions/index.ts

@@ -4,6 +4,7 @@
  */
 
 export * from './a11y/index.ts'
+export * from './dialog/index.ts'
 export * from './emoji/index.ts'
 export * from './reference/index.js'
 export * from './isDarkTheme/index.ts'

src/index.js

@@ -5,7 +5,7 @@
 
 export * from './components/index.js'
 export * from './composables/index.js'
-export * from './functions/index.js'
+export * from './functions/index.ts'
 export * from './directives/index.js'
 export * from './mixins/index.js'
 

styleguide.config.js

@@ -145,6 +145,10 @@ module.exports = async () => {
 						name: 'registerReference',
 						content: 'docs/functions/registerReference.md',
 					},
+					{
+						name: 'spawnDialog',
+						content: 'docs/functions/spawnDialog.md',
+					},
 				],
 			},
 			{

styleguide/global.requires.js

@@ -12,6 +12,7 @@ import Tooltip from './../src/directives/Tooltip/index.js'
 import Focus from './../src/directives/Focus/index.js'
 import Linkify from './../src/directives/Linkify/index.js'
 import { useIsDarkTheme } from '../src/composables/index.js'
+import { spawnDialog } from '../src/functions/dialog/index.ts'
 
 import axios from '@nextcloud/axios'
 
@@ -167,6 +168,7 @@ window.emojiAddRecent = emojiAddRecent
 window.getCurrentSkinTone = getCurrentSkinTone
 window.setCurrentSkinTone = setCurrentSkinTone
 window.usernameToColor = usernameToColor
+window.spawnDialog = spawnDialog
 // Exported composables
 window.useIsDarkTheme = useIsDarkTheme