feat: add API package to register handlers in init scripts

README.md

@@ -146,6 +146,46 @@ OCA.Viewer.close()
 ```
 
 ### 🔍 Add you own file view
+
+If you want to make your app compatible with this app, you can use the methods provided by the [`@nextcloud/viewer`](https://www.npmjs.com/package/@nextcloud/viewer) npm.js package:
+1. Create a vue component which use the `path` and `mime` props (they will be automatically passed by the viewer)
+2. Register your mime viewer with the following:
+   ``` js
+    import { registerHandler } from '@nextcloud/viewer'
+    import VideoView from 'VideoView.vue'
+
+    registerHandler({
+        // unique id
+        id: 'video',
+
+       // optional, it will group every view of this group and
+       // use the proper view when building the file list
+       // of the slideshow.
+       // e.g. you open an image/jpeg that have the `media` group
+       // you will be able to see the video/mpeg from the `video` handler
+       // files that also have the `media` group set.
+       group: 'media',
+
+       // the list of mimes your component is able to display
+       mimes: [
+            'video/mpeg',
+            'video/ogg',
+            'video/webm',
+            'video/mp4'
+        ],
+
+        // your vue component view
+        component: VideoView
+    })
+   ```
+3. Make sure your script is loaded with `\OCP\Util::addInitScript` so that the handler is registered **before** the viewer is loaded.
+4. if you feel like your mime should be integrated on this repo, you can also create a pull request with your object on the `models` directory and the view on the `components` directory. Please have a look at what's already here and take example of it. 🙇‍♀️
+
+
+### Legacy handler registration
+> [!CAUTION]
+> Using OCA.Viewer for registering your handlers is not recommended as this might break depending on the script loading order
+
 If you want to make your app compatible with this app, you can use the `OCA.Viewer` methods
 1. Create a vue component which use the `path` and `mime` props (they will be automatically passed by the viewer)
 2. Register your mime viewer with the following:
@@ -176,4 +216,4 @@ If you want to make your app compatible with this app, you can use the `OCA.View
         component: VideoView
     })
    ```
-3. if you feel like your mime should be integrated on this repo, you can also create a pull request with your object on the `models` directory and the view on the `components` directory. Please have a look at what's already here and take example of it. 🙇‍♀️
+3. Make sure your script is loaded with `\OCP\Util::addScript` (in contrast to using the API package)!

css/viewer-main.css

@@ -1,3 +1,3 @@
 /* extracted by css-entry-points-plugin */
-@import './main-JrgzHO2I.chunk.css';
+@import './main-BbtLvFSi.chunk.css';
 @import './previewUtils-6cpbKhU6.chunk.css';

cypress/e2e/actions/download.cy.ts

@@ -44,8 +44,8 @@ describe(`Download ${fileName} in viewer`, function() {
 	it('Download the image', function() {
 		// open the menu
 		cy.get('body > .viewer .modal-header button.action-item__menutoggle').click()
-		// download the file
-		cy.get('.action-link .download-icon').click()
+		// download the
+		cy.findByRole('menuitem', { name: 'Download' }).click()
 	})
 
 	it('Compare downloaded file with asset by size', function() {

cypress/support/commands.ts

@@ -9,6 +9,8 @@
 import { addCompareSnapshotCommand } from 'cypress-visual-regression/dist/command'
 import { basename } from 'path'
 
+import '@testing-library/cypress/add-commands'
+
 addCommands()
 addCompareSnapshotCommand({
 	errorThreshold: 0.01,
@@ -20,7 +22,7 @@
 /**
  * cy.uploadedFile - uploads a file from the fixtures folder
  *
  * @param {User} user the owner of the file, e.g. admin
  * @param {string} fixture the fixture file name, e.g. image1.jpg
  * @param {string} mimeType e.g. image/png
  * @param {string} [target] the target of the file relative to the user root

cypress/tsconfig.json

@@ -4,6 +4,7 @@
 	"compilerOptions": {
 		"rootDir": "..",
 		"types": [
+			"@testing-library/cypress",
 			"cypress",
 			"dockerode",
 			"node"

package.json

@@ -82,6 +82,7 @@
     "@nextcloud/sharing": "^0.2.5",
     "@nextcloud/stylelint-config": "^3.1.0",
     "@nextcloud/vite-config": "^1.5.6",
+    "@testing-library/cypress": "^10.0.3",
     "@types/dockerode": "^3.3.39",
     "@vue/tsconfig": "^0.5.1",
     "cypress": "^13.17.0",

src/api_package/.gitignore

@@ -0,0 +1,5 @@
+# SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+/dist
+/package-lock.json

src/api_package/README.md

@@ -0,0 +1,47 @@
+<!--
+  - SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors
+  - SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+# Nextcloud Viewer integration
+
+[![REUSE status](https://api.reuse.software/badge/github.com/nextcloud/viewer)](https://api.reuse.software/info/github.com/nextcloud/viewer)
+
+
+## Usage
+### 🔍 Add you own file view
+
+If you want to make your app compatible with this app, you can use the methods provided by the [`@nextcloud/viewer`](https://www.npmjs.com/package/@nextcloud/viewer) npm.js package:
+1. Create a vue component which use the `path` and `mime` props (they will be automatically passed by the viewer)
+2. Register your mime viewer with the following:
+   ``` js
+    import { registerHandler } from '@nextcloud/viewer'
+    import VideoView from 'VideoView.vue'
+
+    registerHandler({
+        // unique id
+        id: 'video',
+
+       // optional, it will group every view of this group and
+       // use the proper view when building the file list
+       // of the slideshow.
+       // e.g. you open an image/jpeg that have the `media` group
+       // you will be able to see the video/mpeg from the `video` handler
+       // files that also have the `media` group set.
+       group: 'media',
+
+       // the list of mimes your component is able to display
+       mimes: [
+            'video/mpeg',
+            'video/ogg',
+            'video/webm',
+            'video/mp4'
+        ],
+
+        // your vue component view
+        component: VideoView
+    })
+   ```
+3. Make sure your script is loaded with `\OCP\Util::addInitScript` so that the handler is registered **before** the viewer is loaded.
+
+> [!TIP]
+> If you feel like your mime should be integrated on this repo, you can also create a pull request with your object on the `models` directory and the view on the `components` directory. Please have a look at what's already here and take example of it. 🙇‍♀️

src/api_package/REUSE.toml

@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+version = 1
+SPDX-PackageName = "@nextcloud/viewer"
+SPDX-PackageSupplier = "2025 Nextcloud GmbH and Nextcloud contributors"
+SPDX-PackageDownloadLocation = "https://github.com/nextcloud/viewer"
+
+[[annotations]]
+path = ["package.json", "tsconfig.json"]
+precedence = "aggregate"
+SPDX-FileCopyrightText = "2025 Nextcloud GmbH and Nextcloud contributors"
+SPDX-License-Identifier = "AGPL-3.0-or-later"

src/api_package/global.d.ts

@@ -0,0 +1,16 @@
+/*!
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ */
+
+import type { IHandler } from './index.ts'
+
+declare global {
+	interface Window {
+		/**
+		 * Registered viewer handlers.
+		 */
+		// eslint-disable-next-line camelcase
+		_oca_viewer_handlers: Map<string, IHandler>
+	}
+}