Merge pull request #1380 from nextcloud-libraries/enh/docs

chore: Enhance docs about generic dialogs and export all related types

lib/components/GenericDialog.vue

@@ -17,12 +17,13 @@
 </template>
 
 <script setup lang="ts">
-import type { ISeverity } from './types.d.ts'
+import type { IDialogButton } from './types'
+
+import { onMounted, onUnmounted } from 'vue'
+import { DialogSeverity } from './types'
 
 import NcDialog from '@nextcloud/vue/dist/Components/NcDialog.js'
 import NcNoteCard from '@nextcloud/vue/dist/Components/NcNoteCard.js'
-import type { IDialogButton } from './types'
-import { onMounted, onUnmounted } from 'vue'
 
 const props = defineProps<{
 	/**
@@ -49,7 +50,7 @@ const props = defineProps<{
 	/**
 	 * Severity of the dialog - if a notecard is used
 	 */
-	severity?: ISeverity
+	severity?: DialogSeverity
 }>()
 
 /**

lib/components/types.ts

@@ -5,7 +5,11 @@
 
 import type { Node } from '@nextcloud/files'
 
-export type ISeverity = 'info' | 'warning' | 'error'
+export enum DialogSeverity {
+	Info = 'info',
+	Warning = 'warning',
+	Error = 'error',
+}
 
 /**
  * Interface for defining buttons passed to the Dialog component
@@ -53,6 +57,6 @@ export interface IFilePickerButton extends Omit<IDialogButton, 'callback'> {
 export type IFilePickerButtonFactory = (selectedNodes: Node[], currentPath: string, currentView: string) => IFilePickerButton[]
 
 /**
-* Type of filter functions to filter the FilePicker's file list
-*/
+ * Type of filter functions to filter the FilePicker's file list
+ */
 export type IFilePickerFilter = (node: Node) => boolean

lib/dialogs.ts

@@ -3,11 +3,14 @@
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
-import type { IDialogButton, ISeverity } from './components/types'
+import type { IDialogButton } from './components/types'
 import type Vue from 'vue'
 
-import GenericDialog from './components/GenericDialog.vue'
+import { DialogSeverity } from './components/types'
 import { spawnDialog } from './utils/dialogs'
+import GenericDialog from './components/GenericDialog.vue'
+
+export { DialogSeverity } from './components/types'
 
 /**
  * This class provides generic Nextcloud themed dialogs
@@ -17,7 +20,7 @@ export class Dialog {
 	#name: string
 	#text: string
 	#buttons: IDialogButton[]
-	#severity?: ISeverity
+	#severity?: DialogSeverity
 	#dialog?: Vue
 
 	/** @deprecated */
@@ -27,7 +30,7 @@ export class Dialog {
 		name: string,
 		text: string,
 		buttons: IDialogButton[] = [],
-		severity?: ISeverity,
+		severity?: DialogSeverity,
 	) {
 		this.#name = name
 		this.#text = text
@@ -80,18 +83,32 @@ export class Dialog {
 
 /**
  * The DialogBuilder provides an easy to use interface for creating simple dialogs in consistent Nextcloud design
+ *
+ * @example
+ * ```ts
+ * // It is recommended to use `getDialogBuilder` instead
+ * const dialogBuilder = new DialogBuilder('The dialog title')
+ * const dialog = dialogBuilder
+ *     .setText('The dialog message')
+ *     .setSeverity(DialogSeverity.Warning)
+ *     .addButton({
+ *         label: 'Ok',
+ *         callback: () => console.warn('Warning was dismissed'),
+ *     })
+ *     .build()
+ * ```
  */
 export class DialogBuilder {
 
-	#severity?: ISeverity
+	#severity?: DialogSeverity
 	#text: string
 	#name: string
 	#buttons: IDialogButton[]
 
-	constructor() {
+	constructor(name?: string) {
 		this.#severity = undefined
 		this.#text = ''
-		this.#name = ''
+		this.#name = name ?? ''
 		this.#buttons = []
 	}
 
@@ -117,7 +134,7 @@ export class DialogBuilder {
 	 * Set the severity of the dialog
 	 * @param severity Severity of the dialog
 	 */
-	setSeverity(severity: ISeverity) {
+	setSeverity(severity: DialogSeverity) {
 		this.#severity = severity
 		return this
 	}
@@ -148,3 +165,21 @@ export class DialogBuilder {
 	}
 
 }
+
+/**
+ * Get the dialog builder to create a new dialog
+ *
+ * @param name The name of the dialog (title)
+ * @example
+ * ```ts
+ * const dialog = getDialogBuilder('Confirm action')
+ *     .addButton({
+ *         label: 'Ok',
+ *         callback: () => console.warn('confirmed'),
+ *     })
+ *     .build()
+ * ```
+ */
+export function getDialogBuilder(name: string) {
+	return new DialogBuilder(name)
+}

lib/index.ts

@@ -37,6 +37,12 @@ export { spawnDialog } from './utils/dialogs.js'
 export {
 	Dialog,
 	DialogBuilder,
+	DialogSeverity,
+	getDialogBuilder,
 } from './dialogs'
 
-export type { IFilePickerButton, IFilePickerFilter } from './components/types.js'
+export type {
+	IDialogButton,
+	IFilePickerButton,
+	IFilePickerFilter,
+} from './components/types.js'