chore: describe JS

.github/workflows/cypress.yml

@@ -1,21 +1,13 @@
-name: Cypress
-on:
-  push:
-    branches:
-      - master
-  pull_request:
-    branches:
-      - master
-
+name: Frontend tests
 env:
-  NODE_VERSION: '16'
+  NODE_VERSION: '20'
   PYTHON_VERSION: '3.9'
 
 permissions:
   contents: read
 
 jobs:
-  cypress:
+  frontend-test:
     runs-on: ubuntu-latest
     services:
       ckan-postgres:
@@ -48,6 +40,11 @@ jobs:
 
     steps:
       - uses: actions/checkout@v3
+      - name: Install Cypress deps
+        run: |
+            apt update
+            apt install -y libgtk2.0-0 libgtk-3-0 libgbm-dev libnotify-dev libnss3 libxss1 libasound2 libxtst6 xauth xvfb
+
       - uses: actions/setup-python@v4
         with:
           python-version: ${{ env.PYTHON_VERSION }}
@@ -56,18 +53,18 @@ jobs:
           node-version: ${{ env.NODE_VERSION }}
 
       - name: Install python deps
-        run: pip install 'ckan[requirements,dev]' -e.
+        run: |
+            git clone --depth 1 --branch ckan-2.10.4 https://github.com/ckan/ckan ../ckan
+            pip install '../ckan[requirements,dev]' -e.
 
       - name: Init environment
         run: |
-            sed -i -e 's/use = config:.*/use = config:\/srv\/app\/src\/ckan\/test-core.ini/' test.ini
-            ckan -c test.ini db upgrade
-            yes | ckan -c test.ini sysadmin add admin password=password123 email=admin@test.net
+          ckan -c test.ini db upgrade
 
       - name: Run Cypress
         uses: cypress-io/github-action@v6
         with:
-          start: ckan -c test-core-cypress.ini run
+          start: ckan -c test.ini run
 
       - uses: actions/upload-artifact@v3
         if: failure()

.github/workflows/typing.yml

@@ -1,5 +1,8 @@
 name: Typing
-on: [pull_request]
+on:
+  pull_request:
+    branches:
+      - master
 env:
   NODE_VERSION: '20'
   PYTHON_VERSION: '3.9'

Makefile

@@ -10,4 +10,7 @@ changelog:  ## compile changelog
 
 
 test-server:
+	yes | ckan -c test.ini db clean
+	ckan -c test.ini db upgrade
+	yes | ckan -ctest.ini sysadmin add admin password=password123 email=admin@test.net
 	ckan -c test.ini run -t

README.md

@@ -957,6 +957,140 @@ Now file can be used normally. You can transfer file ownership to someone,
 stream or modify it. Pay attention to ID: completed file has its own unique ID,
 which is different from ID of the upload.
 
+### JavaScript utilities
+
+None: ckanext-files does not provide stable CKAN JS modules at the moment. Try
+creating your own widgets and share with us your examples or
+requirements. We'll consider creating and including widgets into ckanext-files
+if they are generic enough for majority of the users.
+
+ckanext-files registers few utilities inside CKAN JS namespace to help with
+building UI components.
+
+First group of utilities registered inside CKAN Sandbox. Inside CKAN JS modules
+it's accessible as `this.sandbox`. If you are writing code outside of JS
+modules, Sandbox can be initialized via call to `ckan.sandbox()`
+
+```js
+const sandbox = ckan.sandbox()
+```
+
+When `files` plugin loaded, sandbox contains `files` attribute with two
+members:
+
+* `upload`: high-level helper for uploding files.
+* `makeUploader`: factory for uploader-objects that gives more control over
+  upload process.
+
+The simplest way to upload the file is using `upload` helper.
+
+```js
+await sandbox.files.upload(
+    new File(["file content"], "name.txt", {type: "text/plain"}),
+)
+```
+
+This function uploads file to `default` storage via `files_file_create`
+action. Extra parameters for API call can be passed using second argument of
+upload. Use an object with `requestParams` key. Value of this key will be added
+to standard API request parameters. For example, if you want to use `storage`
+with name `memory` and `field` with value `custom`:
+
+```js
+await sandbox.files.upload(
+    new File(["file content"], "name.txt", {type: "text/plain"}),
+    {requestParams: {storage: "memory", field: "custom"}}
+)
+```
+
+If you need more control over upload, you can create an **uploader** and
+interact with it directly, instead of using `upload` helper.
+
+*Uploader* is an object that extends base uploader, which defines standard
+interface for this object. Uploader perfroms all the API calls internally and
+returns uploaded file details. Out of the box you can use `Standard` and
+`Multipart` uploaders. `Standard` uses `files_file_create` API action and
+specializes on normal uploads. `Multipart` relies on `files_multipart_*`
+actions and can be used to pause and continue upload.
+
+To create uploader instance, pass its name as a string to `makeUploader`. And
+then you can call `upload` method of the uploader to perform the actual
+upload. This method requires two arguments:
+
+* the file object
+* object with additional parameters of API request, the same as `requestParams`
+  from example above. If you want to use default parameters, pass an empty
+  object. If you want to use `memory` storage, pass `{storage: "memory"}`, etc.
+
+```js
+const uploader = sandbox.files.makeUploader("Standard")
+await uploader.upload(new File(["file content"], "name.txt", {type: "text/plain"}), {})
+```
+
+One of the reasons to use manually created uploader is progress
+tracking. Uploader supports event subscriptions via
+`uploader.addEventListener(event, callback)` and here's the list of possible
+upload events:
+
+* `start`: file upload started. Event has `detail` property with object that
+  contains uploaded file as `file`.
+* `progress`: another chunk of file was transferred to server. Event has
+  `detail` property with object that contains uploaded file as `file`, number
+  of loaded bytes as `loaded` and total number of bytes that must be
+  transferred as `total`.
+* `finish`: file upload successfully finished. Event has `detail` property with
+  object that contains uploaded file as `file` and file details from API
+  response as `result`.
+* `fail`: file upload failed. Event has `detail` property with object that
+  contains uploaded file as `file` and object with CKAN validation errors as
+  `reasons`.
+* `error`: error unrelated to validation happened during upload, like call to
+  non-existing action. Event has `detail` property with object that contains
+  uploaded file as `file` and error as `message`.
+
+
+If you want to use `upload` helper with customized uploader, there are two ways
+to do it.
+
+* pass `adapter` property with uploader name inside second argument of `upload`
+  helper:
+  ```js
+  await sandbox.files.upload(new File(...), {adapter: "My"})
+  ```
+* pass `uploader` property with uploader instance inside second argument of `upload`
+  helper:
+  ```js
+  const uploader = sandbox.files.makeUploader("Multipart")
+  await sandbox.files.upload(new File(...), {uploader})
+  ```
+
+The second group of ckanext-files utilities is available as
+`ckan.CKANEXT_FILES` object. This object mainly serves as extension and
+configuration point for `sandbox.files`.
+
+`ckan.CKANEXT_FILES.adapters` is a collection of all classes that can be used
+to initialize uploader. It contains `Standard`, `Multipart` and `Base`
+classes. `Standard` and `Multipart` can be used as is, while `Base` must be
+extended by your custom uploader class. Add your custom uploader classes to
+`adapters`, to make them available application-wide:
+
+```js
+
+class MyUploader extends Base { ... }
+
+ckan.CKANEXT_FILES.adapters["My"] = MyUploader;
+
+await sandbox.files.upload(new File(...), {adapter: "My"})
+```
+
+`ckan.CKANEXT_FILES.defaultSettings` contain the object with default settings
+available as `this.settings` inside any uploader. You can change the name of
+the storage used by all uploaders using this object. Note, changes will apply
+only to uploaders initialized after modification.
+
+```js
+ckan.CKANEXT_FILES.defaultSettings.storage = "memory"
+```
 
 ## File upload strategies
 

ckanext/files/assets/ts/files--modules.ts

@@ -97,7 +97,7 @@ ckan.module("files--auto-upload", function ($) {
                 this.queue.add(file);
                 this.refreshFormState();
                 const options: ckan.CKANEXT_FILES.UploadOptions = {
-                    uploaderParams: [{ uploadAction: this.options.action }],
+                    uploaderArgs: [{ uploadAction: this.options.action }],
                 };
 
                 this.sandbox.files
@@ -370,10 +370,6 @@ ckan.module("files--queue", function ($) {
             widget.on("click", "[data-upload-resume]", this._onWidgetResume);
             widget.on("click", "[data-upload-pause]", this._onWidgetPause);
 
-            info.uploader.addEventListener(
-                "commit",
-                (event: CustomEvent) => (info.id = event.detail.id),
-            );
             info.uploader.addEventListener(
                 "fail",
                 ({

ckanext/files/assets/ts/files--shared.ts

@@ -11,7 +11,7 @@ namespace ckan {
         export interface UploadOptions {
             uploader?: adapters.Base;
             adapter?: string;
-            uploaderParams?: any[];
+            uploaderArgs?: any[];
             requestParams?: { [key: string]: any };
         }
 
@@ -25,12 +25,12 @@ namespace ckan {
             storage: "default",
         };
 
-        function upload(file: File, options: UploadOptions) {
+        function upload(file: File, options: UploadOptions = {}) {
             const uploader =
                 options.uploader ||
                 makeUploader(
                     options.adapter || "Standard",
-                    ...(options.uploaderParams || []),
+                    ...(options.uploaderArgs || []),
                 );
             return uploader.upload(file, options.requestParams || {});
         }
@@ -97,11 +97,6 @@ namespace ckan {
                         new CustomEvent("start", { detail: { file } }),
                     );
                 }
-                dispatchCommit(file: File, id: string) {
-                    this.dispatchEvent(
-                        new CustomEvent("commit", { detail: { file, id } }),
-                    );
-                }
                 dispatchProgress(file: File, loaded: number, total: number) {
                     this.dispatchEvent(
                         new CustomEvent("progress", {
@@ -158,7 +153,6 @@ namespace ckan {
                                 this.dispatchError(file, result);
                                 fail(result);
                             } else if (result.success) {
-                                this.dispatchCommit(file, result.result.id);
                                 this.dispatchFinish(file, result.result);
                                 done(result.result);
                             } else {
@@ -225,7 +219,7 @@ namespace ckan {
                     let info;
 
                     try {
-                        info = await this._initializeUpload(file);
+                        info = await this._initializeUpload(file, params);
                     } catch (err) {
                         if (typeof err === "string") {
                             this.dispatchError(file, err);
@@ -235,7 +229,6 @@ namespace ckan {
                         return;
                     }
 
-                    this.dispatchCommit(file, info.id);
                     this.dispatchStart(file);
 
                     this._doUpload(file, info);
@@ -297,7 +290,7 @@ namespace ckan {
                     this.dispatchFinish(file, info);
                 }
 
-                _initializeUpload(file: File): Promise<UploadInfo> {
+                _initializeUpload(file: File, params: {[key: string]: any}): Promise<UploadInfo> {
                     return new Promise((done, fail) =>
                         this.sandbox.client.call(
                             "POST",
@@ -310,7 +303,7 @@ namespace ckan {
                                     size: file.size,
                                     content_type: file.type,
                                 },
-                                this.settings.initializePayload || {},
+                                params,
                             ),
                             (data: any) => {
                                 done(data.result);