Merge pull request #246 from nextcloud-libraries/fix/files-types

fix: Adjust `OCP.Files` types for `Navigation` and `Router`

lib/v26/OC.d.ts

@@ -1,14 +1,14 @@
 declare namespace Nextcloud.v26 {
 
-    interface OC extends Nextcloud.v25.OC {
+	interface OC extends Nextcloud.v25.OC {
 
-    }
+	}
 
-    interface OCP extends Nextcloud.v25.OCP {
+	interface OCP extends Nextcloud.v25.OCP {
 
-    }
+	}
 
-    interface WindowWithGlobals extends Nextcloud.Common.DayMonthConstants, Window {
+	interface WindowWithGlobals extends Nextcloud.Common.DayMonthConstants, Window {
 
-    }
+	}
 }

lib/v27/OC.d.ts

@@ -1,46 +1,46 @@
 import type { Route } from 'vue-router'
 
 declare global {
-    namespace Nextcloud.v27 {
-        interface FilesRouter {
-            /**
-            * Trigger a route change on the files app
-            * 
-            * @param path the url path, eg: '/trashbin?dir=/Deleted'
-            * @param replace replace the current history (default false)
-            * @see https://router.vuejs.org/guide/essentials/navigation.html#navigate-to-a-different-location
-            */
-            goTo(path: string, replace?: boolean): Promise<Route>;
-        
-            /**
-             * Trigger a route change on the files App
-             *
-             * @param name the route name
-             * @param params the route parameters
-             * @param query the url query parameters
-             * @param replace replace the current history
-             * @see https://router.vuejs.org/guide/essentials/navigation.html#navigate-to-a-different-location
-             */
-            goToRoute(
-                name?: string,
-                params?: Record<string, string>,
-                query?: Record<string, string | (string | null)[] | null | undefined>,
-                replace?: boolean,
-            ): Promise<Route>;
-        }
+	namespace Nextcloud.v27 {
+		interface FilesRouter {
+			/**
+			* Trigger a route change on the files app
+			* 
+			* @param path the url path, eg: '/trashbin?dir=/Deleted'
+			* @param replace replace the current history (default false)
+			* @see https://router.vuejs.org/guide/essentials/navigation.html#navigate-to-a-different-location
+			*/
+			goTo(path: string, replace?: boolean): Promise<Route>;
+		
+			/**
+			 * Trigger a route change on the files App
+			 *
+			 * @param name the route name
+			 * @param params the route parameters
+			 * @param query the url query parameters
+			 * @param replace replace the current history
+			 * @see https://router.vuejs.org/guide/essentials/navigation.html#navigate-to-a-different-location
+			 */
+			goToRoute(
+				name?: string,
+				params?: Record<string, string>,
+				query?: Record<string, string | (string | null)[] | null | undefined>,
+				replace?: boolean,
+			): Promise<Route>;
+		}
 
-        interface OC extends Nextcloud.v26.OC {
+		interface OC extends Nextcloud.v26.OC {
 
-        }
+		}
 
-        interface OCP extends Nextcloud.v26.OCP {
-            Files: {
-                Router: FilesRouter
-            }
-        }
+		interface OCP extends Omit<Nextcloud.v26.OCP, 'Files'> {
+			Files: {
+				Router: FilesRouter
+			}
+		}
 
-        interface WindowWithGlobals extends Nextcloud.Common.DayMonthConstants, Window {
+		interface WindowWithGlobals extends Nextcloud.Common.DayMonthConstants, Window {
 
-        }
-    }
+		}
+	}
 }

lib/v28/OC.d.ts

@@ -1,12 +1,132 @@
 declare namespace Nextcloud.v28 {
 
+	interface ContentsWithRoot {
+		/**
+		 * `@nextcloud/files` Folder
+		 */
+		folder: Record<string, any>
+		/**
+		 * `@nextcloud/files` Node[]
+		 */
+		contents: Record<string, any>[]
+	}
+
+	interface FilesNavigationColumn {
+		/** Unique column ID */
+		id: string
+
+		/** Translated column title */
+		title: string
+
+		/**
+		 * The content of the cell. The element will be appended within
+		 * `node` parameter is of type `@nextcloud/files` Node
+		 */
+		render: (node: Record<string, any>, view: FilesNavigationView) => HTMLElement
+
+		/**
+		 * Function used to sort Nodes between them
+		 * Parameters are of type `@nextcloud/files` Node
+		 */
+		sort?: (nodeA: Record<string, any>, nodeB: Record<string, any>) => number
+		/**
+		 * Custom summary of the column to display at the end of the list.
+		 * Will not be displayed if  nothing is provided
+		 * `node` parameter is of type `@nextcloud/files` Node
+		 */
+		summary?: (node: Record<string, any>[], view: FilesNavigationView) => string
+	}
+
+	interface FilesNavigationView<Column = FilesNavigationColumn> {
+		/** Unique view ID */
+		id: string
+		/** Translated view name */
+		name: string
+		/** The view icon as an inline svg */
+		icon: string
+		/** The view order */
+		order: number
+		/** This view column(s). Name and actions are by default always included */
+		columns?: Column[]
+		/** The empty view element to render your empty content into */
+		emptyView?: (div: HTMLDivElement) => void
+		/** The parent unique ID */
+		parent?: string
+		/** This view is sticky (sent at the bottom) */
+		sticky?: boolean
+		/** This view has children and is expanded or not */
+		expanded?: boolean
+
+		/** Translated accessible description of the view */
+		caption?: string
+
+		/** Translated title of the empty view */
+		emptyTitle?: string
+		/** Translated description of the empty view */
+		emptyCaption?: string
+
+		/**
+		 * Method return the content of the  provided path
+		 * This ideally should be a cancellable promise.
+		 * promise.cancel(reason) will be called when the directory
+		 * change and the promise is not resolved yet.
+		 * You _must_ also return the current directory
+		 * information alongside with its content.
+		 */
+		getContents: (path: string) => Promise<ContentsWithRoot>
+
+		/**
+		 * Custom params to give to the router on click
+		 * If defined, will be treated as a dummy view and
+		 * will just redirect and not fetch any contents.
+		 */
+		params?: Record<string, string>
+
+		/**
+		 * Will be used as default if the user
+		 * haven't customized their sorting column
+		 */
+		defaultSortKey?: string
+	}
+
+	interface FilesNavigation<View = FilesNavigationView> {
+		/**
+		 * Register a new navigation view
+		 */
+		register: (view: View) => void
+
+		/**
+		 * Remove a registered view
+		 */
+		remove: (id: string) => void
+
+		/**
+		 * Set the currently active view
+		 */
+		setActive: (view: View | null) => void
+
+		/**
+		 * Current active view
+		 */
+		active: View | null
+
+		/**
+		 * All registered views
+		 */
+		views: View[]
+	}
+
 	interface OC extends Omit<Nextcloud.v27.OC, 'appSettings'|'addScript'|'addStyle'> {
 		/**
 		 * 'appSettings', 'addScript', and 'addStyle' were removed in Nextcloud 28
 		 */
 	}
 
-	interface OCP extends Nextcloud.v27.OCP {
+	interface OCP extends Omit<Nextcloud.v27.OCP, 'Files'> {
+		Files: {
+			Router: Nextcloud.v27.FilesRouter
+			Navigation: FilesNavigation
+		}
 	}
 
 	interface WindowWithGlobals extends Nextcloud.v27.WindowWithGlobals {