merge: dev into main

.editorconfig

@@ -0,0 +1,11 @@
+# https://editorconfig.org/
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+max_line_length = 80
+indent_style = space
+indent_size = 2

.env

@@ -1,10 +1,36 @@
+# This file is version-controlled and should not be edited.
+# Instead, override these default values by creating .env.local.
+
+# Path where the frontend is served
 BASE=/mink/
-VITE_BACKEND_URL=https://spraakbanken2.it.gu.se/ws/mink/
+
+# Variables beginning with "VITE_" are automatically made available in js.
+
+# Url to the Mink backend
+VITE_BACKEND_URL=https://ws.spraakbanken.gu.se/ws/mink/
+
+# Enable SSL in development
+# DEV_HTTPS_KEY=../spraakbanken.gu.se+1-key.pem
+# DEV_HTTPS_CERT=../spraakbanken.gu.se+1.pem
+
+# Url to SB-Auth
 VITE_AUTH_URL=https://sp.spraakbanken.gu.se/auth/
+# Url to SB-Auth-JWT (defaults to VITE_AUTH_URL + "jwt")
+VITE_JWT_URL=https://sp.spraakbanken.gu.se/auth/jwt
+# SB-Auth logout url
 VITE_LOGOUT_URL=https://sp.spraakbanken.gu.se/Shibboleth.sso/Logout
-# VITE_JWT_URL=https://sp.spraakbanken.gu.se/auth/jwt
+
+# Url to Korp frontend
 VITE_KORP_URL=https://spraakbanken.gu.se/korp/
+
+# Url to Strix frontend
 VITE_STRIX_URL=https://spraakbanken.gu.se/strix/
+
+# Url to a news YAML of the format in https://github.com/spraakbanken/newsdesk
 VITE_NEWS_URL=https://raw.githubusercontent.com/spraakbanken/newsdesk/main/data/mink.yaml
-VITE_MATOMO_URL=https://spraakbanken.gu.se/stats/
-# VITE_MATOMO_ID= # Do not report to the real backend when developing
+
+# Matomo settings. Both need to be set; unset any of them to disable tracking.
+# Url to Matomo backend
+VITE_MATOMO_URL=https://spraakbanken.gu.se/stats
+# Matomo site id
+# VITE_MATOMO_ID= # Do not report to the real backend when developing

CHANGELOG.md

@@ -13,6 +13,27 @@ As this project is a user-facing application, the places in the semantic version
 
 ## [Unreleased]
 
+## [1.7.0] (2024-09-30)
+
+### Added
+
+- Track some events to Matomo [#166](https://github.com/spraakbanken/mink-frontend/issues/166)
+- Added `.editorconfig`
+
+### Changed
+
+- Improved repo documentation
+- Replaced Font Awesome with Phosphor Icons
+- Clearer message of caution next to custom config upload form
+
+### Fixed
+
+- Show loading spinners on the custom config page
+- Show loading spinners when downloading export files
+- Strip slash from Matomo url
+- Backend error messages are ignored when fetching files with "blob" as responseType [#171](https://github.com/spraakbanken/mink-frontend/issues/171)
+- Remove unnecessary scroll bars from HeightResizable, used in code boxes
+
 ## [1.6.1] (2024-08-13)
 
 ### Added
@@ -217,7 +238,8 @@ The frontend is now open to the general public! This version allows users to:
 
 Code changes up until this point are not documented other than in the git commit log.
 
-[unreleased]: https://github.com/spraakbanken/mink-frontend/compare/v1.6.1...HEAD
+[unreleased]: https://github.com/spraakbanken/mink-frontend/compare/v1.7.0...HEAD
+[1.7.0]: https://github.com/spraakbanken/mink-frontend/compare/v1.6.1...v1.7.0
 [1.6.1]: https://github.com/spraakbanken/mink-frontend/compare/v1.6.0...v1.6.1
 [1.6.0]: https://github.com/spraakbanken/mink-frontend/compare/v1.5.0...v1.6.0
 [1.5.0]: https://github.com/spraakbanken/mink-frontend/compare/v1.4.0...v1.5.0

README.md

@@ -1,77 +1,31 @@
-# Mink frontend
-
-<img src="https://spraakbanken.gu.se/themes/sb/images/mink.svg" width="200" alt="Mink logo" />
+<img src="src/assets/mink-slogan-en.svg" width="300" alt="Mink - Språkbanken's data platform" />
 
-With Mink, we are putting Språkbanken's research infrastructure into the hands of the researchers.
+Mink is our effort to put Språkbanken Text’s research infrastructure into the hands of the researchers.
 You can use Mink to apply our language technology methods on texts that you have collected yourself.
-The resulting data can be downloaded or made available through our research tools.
+The resulting data can be downloaded or made available through our research tools, such as Korp and Strix, behind login.
 
 [Use Mink](https://spraakbanken.gu.se/mink/)
-– [Language data](https://spraakbanken.gu.se/en/resources)
-– [Tools](https://spraakbanken.gu.se/en/tools)
-
-## Code
-
-This repo makes up the frontend at [spraakbanken.gu.se/mink](https://spraakbanken.gu.se/mink/).
-It is a [Vue 3](https://v3.vuejs.org/) app using [Vite](https://vitejs.dev/).
-
-### Design patterns
-
-- Single-file components with [`<script setup>`](https://v3.vuejs.org/api/sfc-script-setup.html)
-- [Composables](https://vuejs.org/guide/reusability/composables.html) to group state+logic for distinct features
-- Utility-first styling with [Tailwind CSS](https://tailwindcss.com/)
-- Visualization of API calls:
-  1. Wrap async calls in [`spin`](src/spin/spin.composable.ts):
-     ```js
-     spin(loadCorpora(), "corpora");
-     ```
-  2. For markup that might change after the call, wrap it in [`<PendingContent>`](src/spin/PendingContent.vue) to apply animation:
-     ```html
-     <PendingContent on="corpora"> {{ corpora.length }} </PendingContent>
-     ```
+• [Language data](https://spraakbanken.gu.se/en/resources)
+• [Tools](https://spraakbanken.gu.se/en/tools)
 
-### Futher reading
-
-- [Mink API documentation](https://ws.spraakbanken.gu.se/ws/mink/api-doc)
-- [Mink project board](https://github.com/orgs/spraakbanken/projects/10)
-
-## Recommended IDE setup
-
-[VSCode](https://code.visualstudio.com/) with the plugins
-[ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint),
-[Vue](https://marketplace.visualstudio.com/items?itemName=Vue.volar) and
-[Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode).
-
-VSCode settings:
+# Mink frontend
 
-```json
-{
-  "editor.codeActionsOnSave": {
-    "source.fixAll": "explicit"
-  },
-  "editor.formatOnSave": true,
-  "[javascript][typescript][vue]": {
-    "editor.defaultFormatter": "esbenp.prettier-vscode"
-  },
-  "[json][jsonc]": {
-    "editor.defaultFormatter": "esbenp.prettier-vscode"
-  }
-}
-```
+This code makes up the user interface at [spraakbanken.gu.se/mink](https://spraakbanken.gu.se/mink/).
 
-## SSL in development
+## User documentation
 
-For SB-Auth to allow authentication requests, the dev server must use a hostname matching `*.spraakbanken.gu.se`, and HTTPS must be enabled. See the `server` section in [vite.config.ts](vite.config.ts). If needed, create certificates with [mkcert](https://mkcert.dev) and refer to them in `.env.local`:
+- [Mink](https://spraakbanken.gu.se/en/tools/mink)
+- [User manual](https://spraakbanken.gu.se/en/tools/mink/manual)
+- [Tutorial](https://spraakbanken.gu.se/en/tools/mink/tutorial)
 
-```
-DEV_HTTPS_KEY=./local/spraakbanken.gu.se+1-key.pem
-DEV_HTTPS_CERT=./local/spraakbanken.gu.se+1.pem
-```
+## Developer documentation
 
-## Testing
+- [CHANGELOG.md](CHANGELOG.md)
+- [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md)
+- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+- [docs/STYLE.md](docs/STYLE.md)
 
-See:
+## Contact
 
-- [Vue testing guide](https://vuejs.org/guide/scaling-up/testing.html)
-- [Vitest API](https://vitest.dev/api/)
-- [Vue testing library](https://testing-library.com/docs/vue-testing-library/intro)
+Email Språkbanken Text at: [[email protected]](mailto:[email protected])

docs/ARCHITECTURE.md

@@ -0,0 +1,161 @@
+# Architecture
+
+This is a [Vue 3](https://v3.vuejs.org/) app using the [Vite](https://vitejs.dev/) build tool.
+
+Contents:
+
+1. [System](#system)
+2. [Layout](#layout)
+3. [Vue plugins](#vue-plugins)
+4. [Helper subsystems](#helper-subsystems)
+5. [Testing](#testing)
+
+## System
+
+The Mink system consists of these pieces of software:
+
+- **Mink frontend** runs in the user's web browser and presents a graphical user interface (GUI) to the services of the backend
+- **[Mink backend](https://github.com/spraakbanken/mink-backend)** runs on a server where it manages stored data and executes data processing operations
+- **[Sparv](https://github.com/spraakbanken/sparv-pipeline)** is the NLP pipeline used for text analysis, operated by the Mink backend. (Sparv lives independently from Mink, but it is listed here because it is essential to Mink.)
+
+The frontend communicates with the backend using the [Mink API](https://ws.spraakbanken.gu.se/docs/mink). The API can also be used directly from command-line or scripts.
+
+The Mink system is connected to these other systems:
+
+- **SB-Auth** provides user authentication with [eduGAIN](https://edugain.org/) to Mink and a few other services of Språkbanken Text
+- Analysed results can be installed from Mink into:
+  - **[Korp](https://spraakbanken.gu.se/en/tools/korp)**, Språkbanken's word research platform
+  - **[Strix](https://spraakbanken.gu.se/strix/?lang=eng)**, Språkbanken's text research platform
+- [**Matomo**](https://matomo.org/) records anonymized visitor statistics
+
+## Layout
+
+### Source code
+
+Source code lives in `src/`.
+
+#### Topic folders
+
+Code files are largely ordered into folders by topic:
+
+```
+APIs:
+src/api/ - Mink API and Sparv
+src/auth/ - authentication flow, SB-Auth API
+
+UI components:
+src/components/ - reusable elements like boxes and buttons
+src/page/ - site-wide singular elements (header etc)
+
+Resource pages:
+src/corpus/ - corpus-related pages and logic (most of Mink currently)
+src/metadata/ - metadata-related pages and logic
+src/resource/ - logic common to all resource types
+
+Other pages:
+src/home/ - home page
+src/library/ - overview of user's resources
+src/user/ - user page, admin mode
+
+Plugins:
+src/i18n/ - (internationalization) translations, language switcher
+src/router/ - config for vue-router
+src/store/ - app state
+
+Helper subsystems:
+src/message/ - showing alerts and other feedback messages
+src/spin/ - UI feedback about pending API requests
+```
+
+#### Other code
+
+Directly under `src/` there is:
+
+- Entrypoint (main.ts)
+- Vue root component (App.vue)
+- Vue plugin config
+- Reusable utility functions and types
+- General CSS rules
+
+### User documentation
+
+The user interface should explain itself, as largely as possible without cluttering itself with prose.
+
+Use `<HelpBox>` to give context to a page or section. Form inputs should have a label and probably a help text.
+
+Use icons to accompany text snippets, but not by themselves. Exceptions are allowed in tight spaces.
+
+Outside the app, there is also some guidance available at the Språkbanken Text website: [Mink](https://spraakbanken.gu.se/en/tools/mink).
+
+### Developer documentation
+
+You are reading some of it now. See [README.md](../README.md) for a documentation table of contents.
+
+### Assets
+
+- `public/` contains static assets which do not need to be imported in code
+- `src/assets/` contains static assets which can be imported in code
+
+See [Vite docs on Assets](https://vitejs.dev/guide/assets).
+
+### GitHub action for CI
+
+There is a GitHub action in `.github/workflows/ci.yml` that will trigger on each push and check that the code builds. It also runs tests, but that is less significant since test coverage is tiny so far. As such, it is a basic implementation of the Continuous integration (CI) principle.
+
+## Vue plugins
+
+These are referenced from [main.ts](../src/main.ts). (Tailwind via `index.css`, I think.)
+
+- Page navigation with [vue-router](https://router.vuejs.org/)
+- Reactive app state with [Pinia](https://pinia.vuejs.org/)
+- UI translation with [vue-i18n](https://vue-i18n.intlify.dev/)
+- Utility-first styling with [Tailwind CSS](https://tailwindcss.com/), see [STYLE.md](STYLE.md)
+- Icons with [Phosphor Icons](https://github.com/phosphor-icons/vue)
+- Form handling with [FormKit](https://formkit.com/getting-started)
+- Visitor statistics tracking with [vue-matomo](https://github.com/AmazingDreams/vue-matomo)
+
+## Helper subsystems
+
+These utilities are complex enough that they cannot each be contained in a single file.
+
+### Spin (`src/spin/`)
+
+Wrap an async request with:
+
+```js
+spin(promise, token);
+```
+
+Show loading animation on top of related UI elements with:
+
+```html
+<PendingContent :on="token">[dependent content here]</PendingContent>
+```
+
+### Message (`src/message/`)
+
+Show a message:
+
+```js
+alert("There is no coffee", "error");
+```
+
+Helper for showing a failing Mink API response:
+
+```js
+mink.runJob(corpusId).catch(alertError);
+```
+
+## Testing
+
+Test files should be named after the files they test, so `HomeView.vue` is tested by `HomeView.test.ts`.
+
+Tests are run with `yarn test`
+
+⚠️ Coverage is currently tiny, partly because most features require authentication. We need some kind of mock authentication.
+
+Read more about testing for Vue at:
+
+- [Vue docs on Testing](https://vuejs.org/guide/scaling-up/testing.html)
+- [Vitest API](https://vitest.dev/api/)
+- [Vue testing library](https://testing-library.com/docs/vue-testing-library/intro)

docs/CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing
+
+## Asking a question
+
+Send an email to Språkbanken Text at [[email protected]](mailto:[email protected]) and we will reply as soon as we can.
+
+## Reporting a bug
+
+A _bug_ is a behavior or other problem that clearly goes against how things are supposed to be.
+
+[Create an issue](https://github.com/spraakbanken/mink-frontend/issues/new) and add at least the `bug` label.
+
+For an effective bug report:
+
+- describe how to reproduce the behaviour,
+  - what is expected to happen and
+  - what actually happens
+- mention what web browser and OS you are using
+- add screenshots if relevant
+
+## Suggesting an enhancement
+
+An _enhancement_ could be a new feature, or another improvement that doesn't classify as a bug.
+
+[Create an issue](https://github.com/spraakbanken/mink-frontend/issues/new) and add at least the `enhancement` label.
+
+## Writing some code
+
+Read up on [DEVELOPMENT.md](DEVELOPMENT.md), pick an [issue](https://github.com/spraakbanken/mink-frontend/issues) and get hacking! 👩🏽‍💻