docs: Improve filepicker related documentation and exported types

Signed-off-by: Ferdinand Thiessen <[email protected]>

Author: susnux

l10n/messages.pot

@@ -18,11 +18,11 @@ msgstr ""
 msgid "All files"
 msgstr ""
 
-#: lib/filepicker.ts:183
+#: lib/filepicker.ts:178
 msgid "Choose"
 msgstr ""
 
-#: lib/filepicker.ts:171
+#: lib/filepicker.ts:166
 msgid "Copy"
 msgstr ""
 
@@ -43,8 +43,8 @@ msgstr ""
 msgid "Modified"
 msgstr ""
 
-#: lib/filepicker.ts:177
-#: lib/filepicker.ts:191
+#: lib/filepicker.ts:172
+#: lib/filepicker.ts:186
 msgid "Move"
 msgstr ""
 
@@ -65,6 +65,6 @@ msgstr ""
 msgid "Size"
 msgstr ""
 
-#: lib/toast.ts:229
+#: lib/toast.ts:242
 msgid "Undo"
 msgstr ""

lib/components/FilePicker/FilePicker.vue

@@ -9,7 +9,7 @@
 			<FilePickerBreadcrumbs v-if="currentView === 'files'"
 				:path.sync="currentPath"
 				:show-menu="allowPickDirectory"
-				@create-node="onCreateFolder"/>
+				@create-node="onCreateFolder" />
 			<div v-else class="file-picker__view">
 				<h3>{{ viewHeadline }}</h3>
 			</div>
@@ -28,7 +28,7 @@
 </template>
 
 <script setup lang="ts">
-import type { IFilePickerButton } from '../types'
+import type { IFilePickerButton, IFilePickerFilter } from '../types'
 import { davRootPath, type Node } from '@nextcloud/files'
 
 import DialogBase from '../DialogBase.vue'
@@ -65,7 +65,7 @@ const props = withDefaults(defineProps<{
 	/**
 	 * Custom filter function used to filter pickable files
 	 */
-	filterFn?: (node: Node) => boolean
+	filterFn?: IFilePickerFilter
 
 	/**
 	 * List of allowed mime types

lib/components/types.ts

@@ -23,13 +23,42 @@
 import type { Node } from '@nextcloud/files'
 import type { AsyncComponent, Component } from 'vue'
 
+/**
+ * Interface for defining buttons passed to the Dialog component
+ */
 export interface IDialogButton {
+	/** Label of the button */
 	label: string,
-	icon?: Component | AsyncComponent,
+
+	/** Callback on button click */
 	callback: () => void,
+	/**
+	 * Optional Icon for the button
+	 * Can be a Vue component or async component
+	 */
+	icon?: Component | AsyncComponent,
+
+	/**
+	 * Button type
+	 * @see https://nextcloud-vue-components.netlify.app/#/Components/NcButton
+	 */
 	type?: 'primary' | 'secondary' | 'error' | 'warning' | 'success'
 }
 
+/**
+ * Interface to define buttons of the FilePicker component
+ * The buttons are based on the Dialog buttons but the callback gets the array of selected nodes
+ */
 export interface IFilePickerButton extends Omit<IDialogButton, 'callback'> {
+	/**
+	 * Callback on button click
+	 *
+	 * @param nodes Array of `@nextcloud/files` Nodes that were selected
+	 */
 	callback: (nodes: Node[]) => void
 }
+
+/**
+* Type of filter functions to filter the FilePicker's file list
+*/
+export type IFilePickerFilter = (node: Node) => boolean

lib/filepicker.ts

@@ -20,18 +20,13 @@
  *
  */
 
-import type { IFilePickerButton } from './components/types'
+import type { IFilePickerButton, IFilePickerFilter } from './components/types'
 import type { Node } from '@nextcloud/files'
 
 import { spawnDialog } from './utils/dialogs'
 import { FilePickerVue } from './components/FilePicker/index'
 import { t } from './utils/l10n'
 
-/**
- * Type of filter functions to filter the FilePicker's file list
- */
-export type FilePickerFilter = (node: Node) => boolean
-
 /**
  * @deprecated
  */
@@ -51,15 +46,15 @@ export class FilePicker {
 	private directoriesAllowed: boolean
 	private buttons: IFilePickerButton[]
 	private path?: string
-	private filter?: FilePickerFilter
+	private filter?: IFilePickerFilter
 
 	public constructor(title: string,
 		multiSelect: boolean,
 		mimeTypeFilter: string[],
 		directoriesAllowed: boolean,
 		buttons: IFilePickerButton[],
 		path?: string,
-		filter?: FilePickerFilter) {
+		filter?: IFilePickerFilter) {
 		this.title = title
 		this.multiSelect = multiSelect
 		this.mimeTypeFilter = mimeTypeFilter
@@ -105,7 +100,7 @@ export class FilePickerBuilder {
 	private mimeTypeFilter: string[] = []
 	private directoriesAllowed = false
 	private path?: string
-	private filter?: FilePickerFilter
+	private filter?: IFilePickerFilter
 	private buttons: IFilePickerButton[] = []
 
 	/**
@@ -221,7 +216,7 @@ export class FilePickerBuilder {
 	 *
 	 * @param filter Filter function to apply
 	 */
-	public setFilter(filter: FilePickerFilter): FilePickerBuilder {
+	public setFilter(filter: IFilePickerFilter): FilePickerBuilder {
 		this.filter = filter
 		return this
 	}

lib/index.ts

@@ -1,7 +1,32 @@
-export { FilePicker, FilePickerType, FilePickerBuilder, getFilePickerBuilder } from './filepicker.js'
-export { TOAST_UNDO_TIMEOUT, TOAST_DEFAULT_TIMEOUT, TOAST_PERMANENT_TIMEOUT } from './toast.js'
-export { TOAST_ARIA_LIVE_OFF, TOAST_ARIA_LIVE_POLITE, TOAST_ARIA_LIVE_ASSERTIVE } from './toast.js'
-export { showMessage, showSuccess, showWarning, showInfo, showError, showUndo } from './toast.js'
+export {
+	FilePicker,
+	FilePickerType,
+	FilePickerBuilder,
+	getFilePickerBuilder,
+} from './filepicker.js'
+
+export {
+	ToastAriaLive,
+	ToastType,
+	TOAST_UNDO_TIMEOUT,
+	TOAST_DEFAULT_TIMEOUT,
+	TOAST_PERMANENT_TIMEOUT,
+	TOAST_ARIA_LIVE_OFF,
+	TOAST_ARIA_LIVE_POLITE,
+	TOAST_ARIA_LIVE_ASSERTIVE,
+	showMessage,
+	showSuccess,
+	showWarning,
+	showInfo,
+	showError,
+	showUndo,
+} from './toast.js'
+
+export type {
+	ToastOptions,
+} from './toast.js'
 
 export { spawnDialog } from './utils/dialogs.js'
+
 export { FilePickerVue } from './components/FilePicker/index.js'
+export type { IFilePickerButton, IFilePickerFilter } from './components/types.js'