Merge pull request #62 from i-VRESSE/maxItemsFrom-aware

Make node schema maxItemsFrom and molecule aware

.github/workflows/node.js.yml

@@ -23,3 +23,7 @@ jobs:
     - run: yarn test
     - run: yarn lint
     - run: yarn build
+    - name: Install Playwright
+      run: npx playwright install --with-deps
+    - name: Run integration tests
+      run: yarn test:integration

.gitignore

@@ -4,4 +4,8 @@ dist
 dist-ssr
 *.local
 coverage
+.coverage
 util/__pycache__/
+.yarn
+playwright-report/
+.vscode/

README.md

@@ -9,7 +9,7 @@ The main branch is published at https://wonderful-noether-53a9e8.netlify.app/
 
 ## Develop
 
-Requires [NodeJS](https://nodejs.org/) and [yarn](https://yarnpkg.com/).
+Requires [NodeJS](https://nodejs.org/) and [yarn](https://yarnpkg.com/) (tested with v3.2.1).
 
 ```shell
 # Install dependencies
@@ -20,7 +20,7 @@ yarn dev
 # Goto http://localhost:3000
 ```
 
-### Tests
+### Unit tests
 
 Tests (**/*.test.tsx?) written in [vitetest](https://vitest.dev/) (a test framework similar to [jest](https://jestjs.io/)) can be run with:
 
@@ -36,6 +36,32 @@ yarn  test run --coverage
 
 Creates `coverage/` directory with HTML and LCOV report.
 
+### Integration tests
+
+The integration tests (`integration-tests/**.spec.ts`) are written in [playwright](https://playwright.dev/).
+
+Before running test ensure browsers are installed with
+
+```shell
+npx playwright install
+```
+
+Tests can be run with
+
+```shell
+yarn test:integration
+```
+
+To run in a non-headless browser use
+
+```shell
+yarn test:integration --headed
+```
+
+The browser will pause when a test calls `await page.pause()`, so you can investigate current state.
+
+There is a VS code extension to run integration tests inside editor.
+
 ### Linting
 
 ```shell
@@ -113,6 +139,10 @@ The catalog is a YAML formatted file which tells the app what nodes are availabl
     * map with title as key and link as value
 5. title: Title of the catalog
 
+### schema
+
+See [docs/schema.md](docs/schema.md).
+
 #### uiSchema
 
 See [docs/uiSchema.md](docs/uiSchema.md).

docs/schema.md

@@ -0,0 +1,133 @@
+# Schema
+
+The global and node parameters are validated against a [JSON schema](https://json-schema.org/).
+Also the parameters are edited in a form generated from the JSON schema.
+
+The schema should formatted according to the [JSON schema draft 7](https://json-schema.org/specification-links.html#draft-7) specification.
+
+Besides the keywords and formats defined in the specification and in [ajv-formats](https://github.com/ajv-validator/ajv-formats), the workflow builder adds the following:
+
+## Keyword maxItemsFrom
+
+The `maxItemsFrom` keyword can be used to limit the number of items in an array defined in a schema of a node by the same number of items in a global parameter.
+
+For example to make the `maxItems` of the `nprop` property in the node schema have the same as the length of the global parameter named `gprop` use the following catalog.
+
+```yaml
+title: Test catalog
+global:
+  uiSchema: {}
+  tomlSchema: {}
+  schema:
+    type: object
+    properties:
+      gprop:
+        type: array
+        items:
+          type: string
+categories:
+- name: cat1
+  description: Category 1
+nodes:
+- id: node1
+  category: cat1
+  uiSchema: {}
+  tomlSchema: {}
+  schema:
+    type: object
+    properties:
+      nprop:
+        type: array
+        items:
+          type: string
+        maxItemsFrom: gprop
+```
+
+When global parameters looks like
+
+```json
+{
+    "gprop": ["a", "b"]
+}
+```
+
+Then the schema used for validation and form generation of the node will be
+
+```json
+{
+    "type": "object",
+    "properties": {
+        "nprop": {
+            "type": "array",
+            "items": {
+                "type": "string"
+            },
+            "maxItems": 2
+        }
+    }
+}
+```
+
+The `maxItemsFrom` keyword only works when the property is of type array and the global parameter is also an array.
+
+## Format moleculefilepaths, chain and residue
+
+To restrict the residues sequence numbers or to restrict the possible chains. You can use the `residue` and `chain` formats.
+
+To compute the valid residues sequence numbers of a property the builder needs to know which PDB file that belongs to that property. This is done by annotating the parent array property with `maxItemsFrom: <global parameter name which holds molecule paths>` and annotating that global parameter with `format: moleculefilepaths`.
+
+For example a schema of a node
+
+```yaml
+    type: object
+    properties:
+      seg:
+        type: array
+        maxItemsFrom: molecules
+        title: Segments
+        items:
+          type: array
+          title: Segments of a molecule
+          items:
+            type: object
+            properties:
+              chain:
+                title: Chain
+                type: string
+                format: chain
+              sta:
+                title: Starting residue number
+                type: number
+                format: residue
+              end:
+                title: Ending residue number
+                type: number
+                format: residue
+```
+
+and a global schema
+
+```yaml
+    type: object
+    properties:
+      molecules:
+        title: Input Molecules
+        type: array
+        format: moleculefilepaths
+        items:
+          type: string
+          format: uri-reference
+```
+
+and a PDB file was uploaded to the global parameters
+
+```json
+{
+  "molecules": ["abcd.pdb"]
+}
+```
+
+and `abcd.pdb` file has chain A and B with residues 1, 2, 3 and 4.
+
+Then the form will have restricted the `chain` prop to only allow `A` and `B`
+and will have restricted the sta and end prop to only allow 1, 2, 3 and 4.

integration-tests/data/README.md

@@ -0,0 +1,2 @@
+This directory is a copy of https://github.com/haddocking/haddock3/tree/main/examples/docking-protein-protein/data
+and is used in the integration tests.