From 89e4c9ccacc21628a2d1c0f2f662fd283d800383 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Molakvo=C3=A6?= <skjnldsv@protonmail.com>
Date: Tue, 23 May 2023 10:21:20 +0200
Subject: [PATCH] feat: add files api
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: John Molakvoæ <skjnldsv@protonmail.com>
---
 .../app_upgrade_guide/upgrade_to_27.rst       |  8 +--
 developer_manual/client_apis/activity-api.rst |  6 +-
 developer_manual/client_apis/files.rst        | 58 +++++++++++++++++++
 developer_manual/client_apis/index.rst        |  9 +--
 4 files changed, 67 insertions(+), 14 deletions(-)
 create mode 100644 developer_manual/client_apis/files.rst

diff --git a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_27.rst b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_27.rst
index fafca709024..8a1cd3210d9 100644
--- a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_27.rst
+++ b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_27.rst
@@ -25,13 +25,7 @@ Front-end changes
 Added APIs
 ^^^^^^^^^^
 
-* A new Files Router API allows you to control the files router service and update views, querys or param without page reload (`nextcloud/server#37824 <https://github.com/nextcloud/server/pull/37824>`_)
-
-  .. code-block:: js
-
-    // https://github.com/nextcloud/server/blob/master/apps/files/src/services/RouterService.ts
-    OCP.Files.Router.goTo('/trashbin?dir=/Unsplash.d1680193199')
-    OCP.Files.Router.goToRoute('fileslist', { view: 'files' }, { dir: '/Folders/Group folder' })
+* A new Files Router API allows you to control the files router service and update views, querys or param without page reload. See :doc:`../../client_apis/files`
 
 Back-end changes
 ----------------
diff --git a/developer_manual/client_apis/activity-api.rst b/developer_manual/client_apis/activity-api.rst
index 9d1c4f5d9be..d71d6fe9cfc 100644
--- a/developer_manual/client_apis/activity-api.rst
+++ b/developer_manual/client_apis/activity-api.rst
@@ -1,5 +1,5 @@
-============
-Activity API
-============
+========
+Activity
+========
 
 Find the documentation in the `Activity app repo <https://github.com/nextcloud/activity/blob/master/docs/endpoint-v2.md>`__.
diff --git a/developer_manual/client_apis/files.rst b/developer_manual/client_apis/files.rst
new file mode 100644
index 00000000000..e52b9bd1a02
--- /dev/null
+++ b/developer_manual/client_apis/files.rst
@@ -0,0 +1,58 @@
+=====
+Files
+=====
+
+.. sectionauthor:: John Molakvoæ <skjnldsv@protonmail.com>
+
+Since Nextcloud 27, the files app has been rewritten to use new standards
+and frameworks. This means that the old documentation is no longer valid.
+We will update and document the new files app APIs and methods here.
+
+.. note:: Some external libraries offers in-depth technical documentation.
+    Please have a look at the following:
+    * https://github.com/nextcloud/nextcloud-files (`docs <https://nextcloud.github.io/nextcloud-files/>`_)
+    * https://github.com/nextcloud/nextcloud-upload
+
+
+Router
+^^^^^^
+
+To change views and parameters of the current Files app, we expose the router.
+This directly maps to the Vue router. You can check their own `documentation <https://router.vuejs.org/guide/essentials/navigation.html#navigate-to-a-different-location>`_ to
+better understand the methods.
+
+.. code-block:: ts
+
+  /**
+   * Trigger a route change on the files app
+   * 
+   * @param path the url path, eg: '/trashbin?dir=/Deleted'
+   * @param replace replace the current history
+   * @see https://router.vuejs.org/guide/essentials/navigation.html#navigate-to-a-different-location
+   */
+  goTo(path: string, replace: boolean = false): 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?: Dictionary<string>,
+  	query?: Dictionary<string | (string | null)[] | null | undefined>,
+  	replace?: boolean,
+  ): Promise<Route>
+
+
+Examples
+--------
+
+.. code-block:: js
+
+  OCP.Files.Router.goTo('/trashbin?dir=/Unsplash.d1680193199')
+  OCP.Files.Router.goToRoute('fileslist', { view: 'files' }, { dir: '/Folders/Group folder' })
diff --git a/developer_manual/client_apis/index.rst b/developer_manual/client_apis/index.rst
index f7a8761f921..77f068d8238 100644
--- a/developer_manual/client_apis/index.rst
+++ b/developer_manual/client_apis/index.rst
@@ -7,11 +7,12 @@ Clients and Client APIs
 .. toctree::
     :maxdepth: 2
 
-    general
+    activity-api
     android_library/index
-    WebDAV/index
-    OCS/index
+    files
+    general
     LoginFlow/index
+    OCS/index
     RemoteWipe/index
-    activity-api
+    WebDAV/index