@papaemmelab/isabl-web 0.3.44 → 0.3.45-beta.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +289 -11
- package/dist/isabl-web.common.js +30799 -10524
- package/dist/isabl-web.umd.js +30799 -10524
- package/dist/isabl-web.umd.min.js +16 -16
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
[](https://badge.fury.io/js/@papaemmelab%2Fisabl-web)
|
|
6
6
|
[](https://www.jsdelivr.com/package/npm/isabl-web)
|
|
7
|
-
[![
|
|
7
|
+
[![Run Isabl Web tests][gh_badge]][gh_base]
|
|
8
8
|
[![codecov badge][codecov_badge]][codecov_base]
|
|
9
9
|
[![code style: prettier][prettier_badge]][prettier_base]
|
|
10
10
|
|
|
@@ -14,17 +14,295 @@ Frontend client for [`Isabl`] developed with [Vue.js].
|
|
|
14
14
|
|
|
15
15
|
Learn about [`Isabl`] in the [documentation].
|
|
16
16
|
|
|
17
|
-
##
|
|
17
|
+
## Usage
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
The package is designed to be used directly in HTML via CDN (jsDelivr). Here's a minimal example:
|
|
20
|
+
|
|
21
|
+
```html
|
|
22
|
+
<!DOCTYPE html>
|
|
23
|
+
<html>
|
|
24
|
+
<head>
|
|
25
|
+
<meta charset="utf-8" />
|
|
26
|
+
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
|
|
27
|
+
<meta name="viewport" content="width=device-width,initial-scale=1.0" />
|
|
28
|
+
|
|
29
|
+
<!-- Required: Google Fonts for Roboto and Material Icons -->
|
|
30
|
+
<link
|
|
31
|
+
href="https://fonts.googleapis.com/css?family=Roboto:300,400,500,700|Material+Icons"
|
|
32
|
+
rel="stylesheet"
|
|
33
|
+
type="text/css"
|
|
34
|
+
/>
|
|
35
|
+
|
|
36
|
+
<!-- Required: Material Design Icons -->
|
|
37
|
+
<link
|
|
38
|
+
href="https://cdn.jsdelivr.net/npm/@mdi/font@latest/css/materialdesignicons.min.css"
|
|
39
|
+
rel="stylesheet"
|
|
40
|
+
type="text/css"
|
|
41
|
+
/>
|
|
42
|
+
|
|
43
|
+
<title>Isabl</title>
|
|
44
|
+
</head>
|
|
45
|
+
|
|
46
|
+
<body>
|
|
47
|
+
<div id="isabl-web"></div>
|
|
48
|
+
|
|
49
|
+
<!-- Required: Isabl configuration -->
|
|
50
|
+
<script>
|
|
51
|
+
window.$isabl = {
|
|
52
|
+
apiHost: 'https://your-api-host.com',
|
|
53
|
+
// ... other settings
|
|
54
|
+
};
|
|
55
|
+
</script>
|
|
56
|
+
|
|
57
|
+
<!-- Required: Vue.js 2 -->
|
|
58
|
+
<script src="https://cdn.jsdelivr.net/npm/vue@2"></script>
|
|
59
|
+
|
|
60
|
+
<!-- Required: Isabl Web library -->
|
|
61
|
+
<script src="https://cdn.jsdelivr.net/npm/@papaemmelab/isabl-web@latest"></script>
|
|
62
|
+
</body>
|
|
63
|
+
</html>
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
### Requirements
|
|
67
|
+
|
|
68
|
+
- **Google Fonts**: Roboto font family and Material Icons
|
|
69
|
+
- **Material Design Icons**: CSS from `@mdi/font` package
|
|
70
|
+
- **Vue.js 2**: Required dependency (loaded before isabl-web)
|
|
71
|
+
- **Isabl Configuration**: `window.$isabl` object must be defined before loading the library
|
|
72
|
+
- **Container Element**: A `<div>` with `id="isabl-web"` where the application will mount
|
|
73
|
+
|
|
74
|
+
### Version Pinning
|
|
75
|
+
|
|
76
|
+
For production use, pin to a specific version instead of `@latest`:
|
|
77
|
+
|
|
78
|
+
```html
|
|
79
|
+
<script src="https://cdn.jsdelivr.net/npm/@papaemmelab/isabl-web@0.3.42"></script>
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Or use the beta version:
|
|
83
|
+
|
|
84
|
+
```html
|
|
85
|
+
<script src="https://cdn.jsdelivr.net/npm/@papaemmelab/isabl-web@beta"></script>
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## Development Setup
|
|
89
|
+
|
|
90
|
+
### Prerequisites
|
|
91
|
+
|
|
92
|
+
- Node.js v18.16.1 (npm 9.5.1)
|
|
93
|
+
- Yarn package manager
|
|
94
|
+
- Docker and Docker Compose (for running E2E tests that require the backend API)
|
|
95
|
+
- Git (for cloning the API repository during tests)
|
|
96
|
+
|
|
97
|
+
### Setup Steps
|
|
98
|
+
|
|
99
|
+
1. Clone the repository:
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
git clone https://github.com/papaemmelab/isabl_web.git
|
|
103
|
+
cd isabl_web
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
2. Install Node.js version (using nvm):
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
nvm use v18.16.1
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
If you don't have nvm installed, you can install it from [nvm-sh/nvm](https://github.com/nvm-sh/nvm) or use Node.js v18.16.1 directly.
|
|
113
|
+
|
|
114
|
+
3. Install dependencies:
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
yarn install
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
4. Start the development server:
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
yarn serve
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
The application will be available at `http://localhost:8080` (or the next available port).
|
|
127
|
+
|
|
128
|
+
### Developing against a Production API
|
|
129
|
+
|
|
130
|
+
To connect the development server to a production API instance, you need to modify the API host configuration and work around CORS limitations.
|
|
131
|
+
|
|
132
|
+
1. **Update the API host in `public/index.html`**:
|
|
133
|
+
|
|
134
|
+
Edit `public/index.html` and change the `apiHost` value in the `window.$isabl` configuration:
|
|
135
|
+
|
|
136
|
+
```javascript
|
|
137
|
+
window.$isabl = {
|
|
138
|
+
apiHost: 'https://your-production-api.com', // Change this to your production API URL
|
|
139
|
+
// ... rest of configuration
|
|
140
|
+
}
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
2. **Run Chrome with security disabled** (to bypass CORS restrictions):
|
|
144
|
+
|
|
145
|
+
**⚠️ Warning**: Running Chrome with disabled security should only be done for local development. Never use this for regular browsing as it disables important security features.
|
|
146
|
+
|
|
147
|
+
**macOS/Linux**:
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
# Close all Chrome instances first, then run:
|
|
151
|
+
google-chrome --disable-web-security --user-data-dir=/tmp/chrome_dev_session --disable-features=VizDisplayCompositor
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
**macOS (alternative)**:
|
|
155
|
+
|
|
156
|
+
```bash
|
|
157
|
+
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --disable-web-security --user-data-dir=/tmp/chrome_dev_session --disable-features=VizDisplayCompositor
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
**Windows**:
|
|
161
|
+
|
|
162
|
+
```cmd
|
|
163
|
+
chrome.exe --disable-web-security --user-data-dir="C:\tmp\chrome_dev_session" --disable-features=VizDisplayCompositor
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
3. **Start the development server**:
|
|
167
|
+
|
|
168
|
+
```bash
|
|
169
|
+
yarn serve
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
4. **Access the application**:
|
|
173
|
+
|
|
174
|
+
Open the application in the Chrome instance you started with security disabled. The dev server will connect to your production API.
|
|
175
|
+
|
|
176
|
+
**Note**: The `--user-data-dir` flag creates a separate Chrome profile to avoid affecting your regular Chrome sessions. You can use any temporary directory path.
|
|
177
|
+
|
|
178
|
+
## Testing
|
|
179
|
+
|
|
180
|
+
The test suite includes unit tests (Jest) and end-to-end tests (Cypress).
|
|
20
181
|
|
|
21
|
-
|
|
182
|
+
### Running Unit Tests
|
|
22
183
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
184
|
+
Run unit tests using Jest:
|
|
185
|
+
|
|
186
|
+
```bash
|
|
187
|
+
yarn test:unit
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
This will execute all unit tests in the `tests/unit/` directory.
|
|
191
|
+
|
|
192
|
+
### Running End-to-End Tests
|
|
193
|
+
|
|
194
|
+
E2E tests use Cypress and require the Isabl API backend to be running. The test setup script will automatically clone and start the API if needed.
|
|
195
|
+
|
|
196
|
+
Run E2E tests:
|
|
197
|
+
|
|
198
|
+
```bash
|
|
199
|
+
yarn test:e2e
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
This will:
|
|
203
|
+
|
|
204
|
+
- Start Cypress in interactive mode with Chrome browser
|
|
205
|
+
- Run all E2E test specs from `tests/e2e/specs/`
|
|
206
|
+
|
|
207
|
+
**Note**: E2E tests require Docker and Docker Compose to be installed, as they need to start the backend API in containers.
|
|
208
|
+
|
|
209
|
+
### Running Tests in Headless Mode
|
|
210
|
+
|
|
211
|
+
For CI/CD or automated testing, you can run Cypress in headless mode:
|
|
212
|
+
|
|
213
|
+
```bash
|
|
214
|
+
yarn test:e2e --headless
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
### Creating Test Submissions
|
|
218
|
+
|
|
219
|
+
To create test submission data for E2E tests:
|
|
220
|
+
|
|
221
|
+
```bash
|
|
222
|
+
yarn test:submissions
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
### Running Specific Tests
|
|
226
|
+
|
|
227
|
+
You can run specific test files:
|
|
228
|
+
|
|
229
|
+
```bash
|
|
230
|
+
# Run a specific unit test file
|
|
231
|
+
yarn test:unit tests/unit/TagsField.spec.js
|
|
232
|
+
|
|
233
|
+
# Run a specific E2E test spec
|
|
234
|
+
yarn test:e2e --spec tests/e2e/specs/login.js
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
### Code Coverage
|
|
238
|
+
|
|
239
|
+
To generate and report code coverage:
|
|
240
|
+
|
|
241
|
+
```bash
|
|
242
|
+
yarn test:report-coverage
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
This generates a coverage report and uploads it to Codecov (requires `CODECOV_TOKEN` environment variable).
|
|
246
|
+
|
|
247
|
+
## Publishing
|
|
248
|
+
|
|
249
|
+
The package can be published to npm using the provided scripts. Make sure you're authenticated with npm and have the necessary permissions to publish to the `@papaemmelab` organization.
|
|
250
|
+
|
|
251
|
+
### Publishing Stable Releases
|
|
252
|
+
|
|
253
|
+
To publish a stable release to npm:
|
|
254
|
+
|
|
255
|
+
```bash
|
|
256
|
+
yarn publish-app
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
This command will:
|
|
260
|
+
- Increment the patch version (e.g., `0.3.42` → `0.3.43`)
|
|
261
|
+
- Build the library
|
|
262
|
+
- Publish to npm with the `latest` tag
|
|
263
|
+
|
|
264
|
+
The published version will be available as the default when users install the package:
|
|
265
|
+
```bash
|
|
266
|
+
yarn add @papaemmelab/isabl-web
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
### Publishing Beta Releases
|
|
270
|
+
|
|
271
|
+
To publish a beta/pre-release version:
|
|
272
|
+
|
|
273
|
+
```bash
|
|
274
|
+
yarn publish-beta-app
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
This command will:
|
|
278
|
+
- Increment the patch version and add a beta pre-release identifier (e.g., `0.3.42` → `0.3.43-beta.0`)
|
|
279
|
+
- Build the library
|
|
280
|
+
- Publish to npm with the `beta` tag (not `latest`)
|
|
281
|
+
|
|
282
|
+
Beta versions can be installed using:
|
|
283
|
+
```bash
|
|
284
|
+
yarn add @papaemmelab/isabl-web@beta
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
**Note**: Beta releases do not affect the `latest` tag, so users installing the package normally will continue to get the last stable release.
|
|
288
|
+
|
|
289
|
+
## CI/CD Setup
|
|
290
|
+
|
|
291
|
+
The GitHub Actions workflow requires the following secrets to be configured in the repository settings:
|
|
292
|
+
|
|
293
|
+
### Required Secrets
|
|
294
|
+
|
|
295
|
+
- **`GH_PAT`**: GitHub Personal Access Token for authenticating with GitHub (used to clone the `isabl_demo` repository during tests)
|
|
296
|
+
- **`DOCKER_USERNAME`**: Docker Hub username for the [papaemmelab organization](https://hub.docker.com/orgs/papaemmelab/repositories)
|
|
297
|
+
- **`DOCKER_PASSWORD`**: Docker Hub password or access token for the [papaemmelab organization](https://hub.docker.com/orgs/papaemmelab/repositories)
|
|
298
|
+
- **`CYPRESS_RECORD_KEY`**: Cypress record key for parallel test execution and test recording
|
|
299
|
+
- **`CODECOV_TOKEN`**: Codecov token for the [papaemmelab/isabl_web repository](https://app.codecov.io/gh/papaemmelab/isabl_web)
|
|
300
|
+
|
|
301
|
+
Configure these secrets in your GitHub repository under **Settings → Secrets and variables → Actions**.
|
|
302
|
+
|
|
303
|
+
## Contributing
|
|
304
|
+
|
|
305
|
+
Contributions are welcome, and they are greatly appreciated, check our [contributing guidelines]!
|
|
28
306
|
|
|
29
307
|
## Credits
|
|
30
308
|
|
|
@@ -34,8 +312,8 @@ Isabl was created at [Elli Papaemmanuil's lab].
|
|
|
34
312
|
[Vue.js]: https://vuejs.org/
|
|
35
313
|
[documentation]: https://docs.isabl.io
|
|
36
314
|
[contributing guidelines]: https://docs.isabl.io/contributing-guide
|
|
37
|
-
[
|
|
38
|
-
[
|
|
315
|
+
[gh_badge]: https://github.com/papaemmelab/isabl_web/actions/workflows/run-tests.yaml/badge.svg
|
|
316
|
+
[gh_base]: https://github.com/papaemmelab/isabl_web/actions/workflows/run-tests.yaml
|
|
39
317
|
[codecov_badge]: https://codecov.io/gh/papaemmelab/isabl_web/graph/badge.svg?token=OWWLDGVFJ5
|
|
40
318
|
[codecov_base]: https://codecov.io/gh/papaemmelab/isabl_web
|
|
41
319
|
[prettier_badge]: https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square
|