@indiscale/linkahead-webui-ext-map 0.5.0

package/.eslintrc.json

@@ -0,0 +1,45 @@
+{
+  "parser": "@babel/eslint-parser",
+  "env": {
+    "node": true,
+    "browser": true,
+    "es2021": true,
+    "jest/globals": true
+  },
+  "extends": [
+    "eslint:recommended",
+    "plugin:react/recommended",
+    "plugin:react-hooks/recommended",
+    "plugin:jsx-a11y/recommended"
+  ],
+  "parserOptions": {
+    "ecmaVersion": "latest",
+    "sourceType": "module",
+    "requireConfigFile": false
+  },
+  "ignorePatterns": ["*.scss", "**/*.test.js"],
+  "plugins": ["react", "jsx-a11y", "jest"],
+  "rules": {
+    "react/react-in-jsx-scope": "off",
+    "react/jsx-uses-react": "off"
+  },
+  "settings": {
+    "react": { "version": "detect" }
+  },
+  "overrides": [
+    {
+      "files": ["**/*.{ts,tsx}"],
+      "parser": "@typescript-eslint/parser",
+      "plugins": ["@typescript-eslint"],
+      "extends": ["plugin:@typescript-eslint/recommended"],
+      "rules": {
+        "@typescript-eslint/naming-convention": [
+          "error",
+          { "selector": "typeLike", "format": ["PascalCase"], "prefix": ["T"] }
+        ],
+        "react/prop-types": "off",
+        "@typescript-eslint/no-explicit-any": "off"
+      }
+    }
+  ]
+}

package/.gitlab-ci.yml

@@ -0,0 +1,44 @@
+default:
+  image: node:18
+  tags:
+    - docker
+
+stages:
+  - build
+  - test
+
+install:
+  stage: build
+  script:
+    - npm install --verbose
+  cache:
+    paths:
+      - node_modules/
+  artifacts:
+    expire_in: 1 days
+    when: on_success
+    paths:
+      - node_modules/
+
+unittests:
+  stage: test
+  dependencies:
+    - install
+  script:
+    - npm test -- --coverage
+
+linting:
+  stage: test
+  dependencies:
+    - install
+  script:
+    - npm run lint
+
+audit:
+  stage: test
+  dependencies:
+    - install
+  script:
+    # Run audit and fail on vulnaribilities with high or critical severity, we
+    # accept moderate for now.
+    - npm audit --audit-level high

package/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.5.0] - 2026-06-11
+
+### Changed
+
+* Renamed to LinkAhead Ext Map
+
+## [0.4.0] - 2026-01-28
+
+### Added
+
+- Loading Provider which shows spinner on layer change.
+- The contents of the marker popup can now be configured for each select path by adding a config like
+
+  ```json
+  "entityPreview": {
+    "myPath": {
+      "query": "SELECT id, title, Publication year FROM Record WITH id = {id}",
+      "format": "<br><span><b>id: </b>{id}</span><span><b>title: </b>{title}</span><span><b>Publication year: </b>{Publication year}</span>"
+    }
+  }
+  ```
+
+  to your `ext_map.json` file where the `query` is executed for each pin upon clicking on the marker and the expressions in `{}` in the `format` string are replaced by the selector values.
+
+- The preview also works in standalone mode when setting the preview path with the `iframeSettings.entityPreviewPath` variable (default is "same").
+- Optional `default_view`, `zoom`, and `center` config keys to set default view, zoom, and center of standalone map independently from regular config
+
+### Changed
+
+- Entity links now open in new tab for entities that are not on the same page as the current map view.
+- Partial implementation of typescript.
+
+### Removed
+
+- `tools/copy-map-into-webui.sh` Has been moved to a more generic helper script in linkahead-webui-legacy-adapter.
+
+### Fixed
+
+- Environment variables are read-in correctly when running, e.g., `GRPC_API_URI="https://example.com" npm run build`
+- Wrong CSS order in mock/standalone map which resulted in entity parent names being white on white background
+
+## [0.3.0] - 2025-09-15
+
+### Added
+
+- Added query option so that in standalone mode, we can fetch and display the current page entities on the map i.e pins
+  using a query string which is produced using variables from the URL and a format string / template which we get from LinkAhead's map config `ext_map.json`.
+- Updated npm run commands with dev options see README.md for details
+- Added custom Spinner / Loader for the Map when loading pins and for when the stage before the map appears onscreen
+- Added Cypress for End to End testing
+
+### Fixed
+
+- [#257](https://gitlab.com/linkahead/linkahead-webui/-/issues/257) Fix to show spinner properly centred on the screen.
+
+## [0.2.0] - 2025-08-20
+
+### Added
+
+- Added Standalone mode, whereby parts of the map can be hidden. e.g layers control, query search button and path switch.
+- Added Script for MAC / Bash to automate the copying of the Map through the legacy-adapter, then into caosdb-webui and finally into the Docker container.
+
+### Fixed
+
+- [https://gitlab.indiscale.com/caosdb/customers/leibniz-zmt/management/-/issues/265] Fix to hide map when entering Edit Mode. Also fixed that the map should show upon startup if in the config "show": true is set
+
+## [0.1.0]
+
+### Added
+
+- Everything

package/README.md

@@ -0,0 +1,97 @@
+# LinkAhead Webui Ext Map
+
+Map extension for the CaosDB Webui based on Leaflet and React.
+
+## Available Scripts
+
+In the project directory, you can run:
+
+### `npm run mock`
+
+Runs the map in the development mode.\
+Open [http://localhost:3000](http://localhost:3000) to view it in your browser.
+
+The page will reload when you make changes.\
+You may also see any lint errors in the console.
+
+### `npm run mock:standalone`
+
+Shows the map component only configured in accordance with the standalone.config.js file in the root directory.
+
+### `npm run mock:dev:standalone`
+
+As above but accesses Linkahead instance through defined URL in webpack.config.js
+
+### `npm run build:standalone`
+
+Builds the map component configured in accordance with the standalone.config.js file in the root directory and without the toggle button.
+
+### `npm run build:dev:standalone`
+
+As above but accesses Linkahead instance through defined URL in webpack.config.js
+
+### `npx serve -s dist -l 5000`
+
+In order to test standalone iFrame
+
+- Configure the /select_query.json file to have the appropriate format string
+- Configure the src parameter in the Iframe - iframe/index.html - to be the url of the npx server and an appropriate query string
+  e.g http://localhost:5000?authorId=14104
+- We support multiple and optional entries here if the FormatString is correctly specified e.g
+  `formatString: "SELECT id, name, parent, Event.latitude, Event.longitude FROM Dataset WITH AN authors=${authorId} [[ OR authors=${authorId} ]]",` Here we have one optional block so the authorId can be optionally included in the Url or not (and this supports multiple authorId's). The very first authorsId in the string is required ``[[ ]]` square brackets signify that this part is optional.
+- To include multiple id's in the URL use as follows: http://localhost:5000?authorId=14104,1607,1908
+- Run `npm run build:standalone` first, then the above npx command. This runs a web server of the built version of the standalone app.
+- In the browser open ${YOUR_PATH_TO_THE \_CODE}/caosdb-webui-ext-map/iframe/index.html
+
+### `npm test`
+
+Launches the test runner in the interactive watch mode.\
+See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information.
+
+### `npm cypress`
+
+Launches Cypress GUI. Info here from their website: https://docs.cypress.io/app/end-to-end-testing/testing-your-app
+
+- Make sure `npm run build:dev:standalone` is running the app
+- Open Cypress with above command
+- To test select E2E Testing
+- Select Test file which at the time of writing, only standalone-map is available
+
+### `npm cypress:run`
+
+Runs all Cypress tests in commandline.
+
+### `npm cypress:cicd`
+
+Command to run all Cypress tests in commandline when weburl is reachable and with addition of custom URL
+e.g if Pipeline using Bash: URL=http://localhost:8082/?authorId=14104 npm run cypress:cicd
+
+### `npm run build`
+
+Builds the app for production to the `build` folder.\
+It correctly bundles React in production mode and optimizes the build for the best performance.
+
+The build is minified and the filenames include the hashes.\
+Your app is ready to be deployed!
+
+See the section about [deployment](https://facebook.github.io/create-react-app/docs/deployment) for more information.
+
+### `npm run format`
+
+Runs the formatter (prettier) on the `src/` directory.
+
+### `npm run lint`
+
+Runs the linter (eslint) on the `src/` directory.
+
+### `npm run tsc`
+
+Runs typescript test of all typescript files (excepting explicity ignored ones).
+
+## Deployment (with LinkAhead)
+
+1. Build the bundle in the react map repo with `npm run build`.
+2. Copy the build directory to `custom/caosdb-server/caosdb-webui/src/ext/include/reactmap`.
+3. Provide a `ext_map.json` under `custom/caosdb-server/caosdb-webui/conf/ext/json/ext_map.json`.
+4. Start linkahead with envoy enabled and with webui ref = `f-react-map`.
+5. Browse to localhost:8081. Optionally insert test data via `./misc/map_test_data.py`.

package/RELEASE_GUIDELINES.md

@@ -0,0 +1,45 @@
+# Release guidelines for the CaosDB WebUI legacy adapter module
+
+This document specifies release guidelines in addition to the general release
+guidelines of the CaosDB Project
+([RELEASE_GUIDELINES.md](https://gitlab.com/caosdb/caosdb/blob/dev/RELEASE_GUIDELINES.md))
+
+## General Prerequisites
+
+* All tests are passing.
+* FEATURES.md is up-to-date and a public API is being declared in that document.
+* CHANGELOG.md is up-to-date.
+* dependencies in `package.json` are up-to-date.
+
+## Steps
+
+
+1. Create a release branch from the dev branch. This prevents further changes
+   to the code base and a never ending release process. Naming: `release-<VERSION>`
+
+2. Update CHANGELOG.md
+
+3. Check all general prerequisites.
+
+4. Update the version:
+   * The `version` variable in `package.json`
+
+5. Merge the release branch into the main branch.
+
+6. Tag the latest commit of the main branch with `v<VERSION>`.
+
+7. Delete the release branch.
+
+8. Publish the release by executing `npm publish` which uploads the caosdb
+   module to the node package repository [npmjs.com](https://www.npmjs.com).
+
+9. Merge the main branch back into the dev branch.
+
+10. After the merge of main to dev, start a new development version by
+    increasing at least the patch version of the `version` in
+    [package.json](./package.json) and preparing CHANGELOG.md by adding a new
+    "Unreleased" section on top.
+
+11. Create releases on gitlab.com and gitlab.indiscale.com that contain (at
+    least) the most recent section of the CHANGELOG as the description and link
+    to the NPM module.

package/__mocks__/fileMock.js

@@ -0,0 +1,3 @@
+// __mocks__/fileMock.js
+
+module.exports = "test-file-stub";

package/__mocks__/styleMock.js

@@ -0,0 +1 @@
+module.exports = {};

package/babel.config.js

@@ -0,0 +1,22 @@
+// babel.config.js
+module.exports = function (api) {
+  api.cache(true);
+
+  const presets = [
+    [
+      "@babel/preset-env",
+      {
+        targets: { node: "current" },
+
+        // IMPORTANT for Jest: transpile ESM -> CommonJS
+        modules: "commonjs",
+      },
+    ],
+    ["@babel/preset-react", { runtime: "automatic" }],
+    ["@babel/preset-typescript", { allExtensions: true, isTSX: true }],
+  ];
+
+  const plugins = [];
+
+  return { presets, plugins };
+};

package/cypress/e2e/standalone-map.cy.js

@@ -0,0 +1,55 @@
+/// <reference types="cypress" />
+
+const URL = "http://localhost:8082/?authorId=14104";
+
+describe("Test standalone map", () => {
+  describe("fast checks (fresh visit each test)", () => {
+    beforeEach(() => {
+      cy.visit(URL);
+    });
+
+    it("displays loader initially while loading map", () => {
+      cy.get('[data-testid="mapLoader"]').should("exist");
+    });
+
+    it("loads Graticule Module", () => {
+      cy.window().then((win) => {
+        expect(win.L, "window.L exists").to.exist;
+        expect(win.L.latlngGraticule, "latlngGraticule registered").to.be.a(
+          "function"
+        );
+      });
+    });
+
+    it("displays map", () => {
+      cy.get(".leaflet-container").should("exist");
+    });
+
+    it("when map loads, loader appears while fetching pins", () => {
+      cy.get(".leaflet-container").should("exist");
+      cy.get('[data-testid="mapLoader"]').should("exist");
+    });
+  });
+
+  // Suite-level override (the only supported way)
+  // to stop upon each successive test that all state is re-rendered etc
+  describe(
+    "pins flow (reuse state from previous test)",
+    { testIsolation: false },
+    () => {
+      it("displays pins on map with query", () => {
+        cy.visit(URL);
+        cy.wait(20000);
+        cy.get('[data-testid="loader"]').should("not.exist");
+        cy.get(".leaflet-marker-icon").as("pins");
+        cy.get("@pins").should("have.length.greaterThan", 0);
+      });
+
+      it("click on pin shows popup (uses previous state)", () => {
+        // no visit here -> we reuse the same page/session from the previous test
+        cy.get(".leaflet-marker-icon").first().click({ force: true });
+        cy.get(".leaflet-popup-content-wrapper").should("exist");
+      });
+    }
+  );
+});

package/cypress/support/commands.js

@@ -0,0 +1,25 @@
+// ***********************************************
+// This example commands.js shows you how to
+// create various custom commands and overwrite
+// existing commands.
+//
+// For more comprehensive examples of custom
+// commands please read more here:
+// https://on.cypress.io/custom-commands
+// ***********************************************
+//
+//
+// -- This is a parent command --
+// Cypress.Commands.add('login', (email, password) => { ... })
+//
+//
+// -- This is a child command --
+// Cypress.Commands.add('drag', { prevSubject: 'element'}, (subject, options) => { ... })
+//
+//
+// -- This is a dual command --
+// Cypress.Commands.add('dismiss', { prevSubject: 'optional'}, (subject, options) => { ... })
+//
+//
+// -- This will overwrite an existing command --
+// Cypress.Commands.overwrite('visit', (originalFn, url, options) => { ... })

package/cypress/support/e2e.js

@@ -0,0 +1,17 @@
+// ***********************************************************
+// This example support/e2e.js is processed and
+// loaded automatically before your test files.
+//
+// This is a great place to put global configuration and
+// behavior that modifies Cypress.
+//
+// You can change the location of this file or turn off
+// automatically serving support files with the
+// 'supportFile' configuration option.
+//
+// You can read more here:
+// https://on.cypress.io/configuration
+// ***********************************************************
+
+// Import commands.js using ES2015 syntax:
+import './commands'

package/cypress.config.js

@@ -0,0 +1,10 @@
+const { defineConfig } = require("cypress");
+
+module.exports = defineConfig({
+  e2e: {
+    supportFile: "cypress/support/e2e.js",
+    setupNodeEvents(on, config) {
+      // implement node event listeners here
+    },
+  },
+});

package/dist/index.html

@@ -0,0 +1 @@
+<!doctype html><html lang="en"><head><meta charset="utf-8"/><script defer="defer" src="linkahead-webui-ext-map.js"></script></head><body><noscript>You need to enable JavaScript to run this app.</noscript><div id="caosdb-f-map-panel"></div><div id="caosdb-f-toggle-map-button"></div></body></html>