Merge pull request #12168 from nextcloud/enh/dev-31-files-sharing

feat(developer): Add initial changes for Nextcloud 31

developer_manual/app_publishing_maintenance/app_upgrade_guide/index.rst

@@ -11,6 +11,7 @@ These sub pages will cover the most important changes in Nextcloud, as well as s
 .. toctree::
    :maxdepth: 1
 
+   upgrade_to_31.rst
    upgrade_to_30.rst
    upgrade_to_29.rst
    upgrade_to_28.rst

developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_31.rst

@@ -0,0 +1,86 @@
+=======================
+Upgrade to Nextcloud 31
+=======================
+
+General
+-------
+
+- TBD
+
+Front-end changes
+-----------------
+
+Logical position CSS rules
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+With Nextcloud 31 all server provided styles are migrated to use `logical positioning <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values>`_
+instead of physical, this allows the front-end layout to adjust to different language directions (right-to-left).
+App developers are strongly encouraged to migrate their apps to logical positioning too.
+
+Examples for logical vs physical positioning:
+
+- ``margin-inline-start: 4px;`` instead of ``margin-left: 4px;``
+- ``inset-inline-end: 8px;`` instead of ``right: 8px``
+
+Files and Files sharing
+^^^^^^^^^^^^^^^^^^^^^^^
+
+With Nextcloud 28 the Files app front-end was migrated to Vue and the private API ( ``OCA.Files`` ) was removed,
+but for public shares the legacy frontend-end was still used. With Nextcloud 31 public shares also use the new Vue front-end.
+This means accessing the legacy private API in ``OCA.Files`` is no longer possible, all existing apps should migrate to the :ref:`public API<js-library_nextcloud-files>`.
+
+To make migration easier utility functions are provided in the ``@nextcloud/sharing`` :ref:`package<js-library_nextcloud-sharing>`
+to check whether the current Files app instance is a public share or not, and if so to fetch the share token.
+
+.. code-block:: JavaScript
+
+    import { isPublicShare, getSharingToken } from '@nextcloud/sharing/public'
+    
+    if (isPublicShare()) {
+        console.info('This is a public share with the sharing token: ', getSharingToken())
+    }
+
+
+Added APIs
+^^^^^^^^^^
+
+- TBD
+
+Changed APIs
+^^^^^^^^^^^^
+
+- TBD
+
+Deprecated APIs
+^^^^^^^^^^^^^^^
+
+- TBD
+
+Removed APIs
+^^^^^^^^^^^^
+
+- ``OCA.FilesSharingDrop`` removed as part of the Vue migration. Use the Files app API provided by the :ref:`package<js-library_nextcloud-files>` .
+
+
+Back-end changes
+----------------
+
+Added APIs
+^^^^^^^^^^
+
+- TBD
+
+Changed APIs
+^^^^^^^^^^^^
+
+- TBD
+
+Deprecated APIs
+^^^^^^^^^^^^^^^
+
+- TBD
+
+Removed APIs
+^^^^^^^^^^^^
+
+- TBD

developer_manual/digging_deeper/javascript-apis.rst

@@ -67,10 +67,13 @@ This package provides a simple event bus implementation that integrates with ser
 
 This package provides access to UI dialogs in Nextcloud. Documentation: https://nextcloud-libraries.github.io/nextcloud-dialogs/
 
+.. _js-library_nextcloud-files:
+
 ``@nextcloud/files``
 ^^^^^^^^^^^^^^^^^^^^
 
-This package provides helper functions around the Files app. Documentation: https://nextcloud-libraries.github.io/nextcloud-files/
+This package provides methods to access the public API of the Files app, helper functions to access Nextcloud files using WebDAV,
+and utility functions to work with files and folders. Documentation: https://nextcloud-libraries.github.io/nextcloud-files/
 
 ``@nextcloud/initial-state``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -107,6 +110,14 @@ This package provides various helpers for file and folder paths. Documentation:
 
 This package provides helpers to generate URLs, e.g. to access assets and REST APIs of your app or the Nextcloud server. Documentation: https://nextcloud-libraries.github.io/nextcloud-router/
 
+.. _js-library_nextcloud-sharing:
+
+``@nextcloud/sharing``
+^^^^^^^^^^^^^^^^^^^^^^
+
+This package provides helpers interact with the Files sharing app, e.g. to detect if the current page is a public share and retrieving the sharing token.
+Documentation: https://nextcloud-libraries.github.io/nextcloud-sharing/
+
 ``@nextcloud/vue``
 ^^^^^^^^^^^^^^^^^^