feat: plugin methods center/zoom/overview-image

docs/plugins/map/position.md

+### Map positon
+
+With use of the methods below plugins can access and modify user position data.
+
+#### Get zoom
+
+To get current zoom value, plugins can use the `window.minerva.map.getZoom()` method, which returns current zoom value as a number.
+
+**Example:**
+
+```ts
+const currentZoom = window.minerva.map.getZoom();
+console.log(currentZoom); // 5
+```
+
+#### Set zoom
+
+To modify current zoom value, plugins can use the `window.minerva.map.setZoom(zoom)` method. This function accepts non-negative number as an argument and returns nothing. If argument is invalid, `setZoom` method throws an error.
+
+**Valid example:**
+
+```ts
+window.minerva.map.setZoom(7.54);
+console.log(window.minerva.map.getZoom()); // 7.54
+```
+
+**Invalid example:**
+
+```ts
+window.minerva.map.setZoom(-14);
+// Uncaught ZodError: [...]
+```
+
+#### Get center
+
+User position is defined as center coordinate. It's value is defined as x/y/z points of current viewport center translated to map position. Plugins can access center value and modify it.
+
+To get current position value, plugins can use the `window.minerva.map.getCenter()` method which returns current position value as an object containing `x`, `y` and `z` fields. All of them are non-negative numbers but `z` is an optional field and it defines current zoom value. If argument is invalid, `getCenter` method throws an error.
+
+**Valid example:**
+
+```ts
+const currentCenter = window.minerva.map.getCenter();
+console.log(currentCenter); // {x: 13256, y: 8118, z: 5}
+```
+
+#### Set center
+
+To modify position center value plugins can use `window.minerva.map.setCenter(positionObject)` which accepts single object as an argument and returns nothing. This object should contain `x`, `y` fields and `z` optionally. All of them are non-negative numbers. If argument is invalid, `setCenter` method throws an error.
+
+**Valid example:**
+
+```ts
+window.minerva.map.setCenter({ x: 13256, y: 8118, z: 5 });
+console.log(window.minerva.map.getCenter()); // {x: 13256, y: 8118, z: 5}
+```
+
+**Invalid example:**
+
+```ts
+window.minerva.map.setCenter({ x: 13256, y: 8118, z: -5 });
+// Uncaught ZodError: [...]
+```

docs/plugins/overview-images.md

+### Overview images
+
+The methods contained within 'Overview images' are used to access data on Overview images and modify behavior of Overview images modal.
+
+Below is a description of the methods, as well as the types they return. description of the object types can be found in folder `/docs/types/`.
+
+**Available data access methods include:**
+
+- `getCurrentOverviewImage`
+  - gets currently selected overview image
+  - returns `OverviewImageView` or `undefined`
+- `getOverviewImage`
+  - gets all loaded overview images
+  - returns array of `OverviewImageView`
+
+**Available data modify methods include:**
+
+##### `hideOverviewImageModal`
+
+- accepts no arguments
+- hides overview image modal if opened
+- returns nothing
+- example:
+  ```ts
+  window.minerva.overviewImage.hideOverviewImageModal();
+  ```
+
+##### `selectOverviewImage`
+
+- accepts single argument of number representing id of one of loaded overview images
+- selects overview image of provided id as current, if image does not exists throws an error
+- returns nothing
+- example:
+  ```ts
+  window.minerva.overviewImage.selectOverviewImage(42);
+  ```
+
+##### `showOverviewImageModal`
+
+- accepts single argument of number representing id of one of loaded overview images
+- selects overview image of provided id as current and opens overview image modal, if image does not exists throws an error
+- returns nothing
+- example:
+  ```ts
+  window.minerva.overviewImage.showOverviewImageModal(24);
+  ```

docs/types/OverviewImageView.md

+```json
+{
+  "type": "object",
+  "properties": {
+    "idObject": {
+      "type": "number"
+    },
+    "filename": {
+      "type": "string"
+    },
+    "width": {
+      "type": "number"
+    },
+    "height": {
+      "type": "number"
+    },
+    "links": {
+      "type": "array",
+      "items": {
+        "anyOf": [
+          {
+            "type": "object",
+            "properties": {
+              "idObject": {
+                "type": "number"
+              },
+              "polygon": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "x": {
+                      "type": "number"
+                    },
+                    "y": {
+                      "type": "number"
+                    }
+                  },
+                  "required": ["x", "y"],
+                  "additionalProperties": false
+                }
+              },
+              "imageLinkId": {
+                "type": "number"
+              },
+              "type": {
+                "type": "string"
+              }
+            },
+            "required": ["idObject", "polygon", "imageLinkId", "type"],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "idObject": {
+                "type": "number"
+              },
+              "polygon": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/definitions/overviewImageView/properties/links/items/anyOf/0/properties/polygon/items"
+                }
+              },
+              "zoomLevel": {
+                "type": "number"
+              },
+              "modelPoint": {
+                "$ref": "#/definitions/overviewImageView/properties/links/items/anyOf/0/properties/polygon/items"
+              },
+              "modelLinkId": {
+                "type": "number"
+              },
+              "type": {
+                "type": "string"
+              }
+            },
+            "required": ["idObject", "polygon", "zoomLevel", "modelPoint", "modelLinkId", "type"],
+            "additionalProperties": false
+          }
+        ]
+      }
+    }
+  },
+  "required": ["idObject", "filename", "width", "height", "links"],
+  "additionalProperties": false
+}
+```

index.d.ts

 import { getModels } from '@/services/pluginsManager/map/models/getModels';
-import { OpenMapArgs, openMap } from '@/services/pluginsManager/map/openMap';
+import { openMap } from '@/services/pluginsManager/map/openMap';
+import { getCenter } from '@/services/pluginsManager/map/position/getCenter';
+import { setCenter } from '@/services/pluginsManager/map/position/setCenter';
 import { triggerSearch } from '@/services/pluginsManager/map/triggerSearch';
+import { getZoom } from '@/services/pluginsManager/map/zoom/getZoom';
+import { setZoom } from '@/services/pluginsManager/map/zoom/setZoom';
 import { MinervaConfiguration } from '@/services/pluginsManager/pluginsManager';
-import { MapModel } from '@/types/models';
 import { getDisease } from '@/services/pluginsManager/project/data/getDisease';
 import { getName } from '@/services/pluginsManager/project/data/getName';
 import { getOrganism } from '@/services/pluginsManager/project/data/getOrganism';
@@ -40,6 +43,17 @@ declare global {
         };
         openMap: typeof openMap;
         triggerSearch: typeof triggerSearch;
+        getZoom: typeof getZoom;
+        setZoom: typeof setZoom;
+        getCenter: typeof getCenter;
+        setCenter: typeof setCenter;
+      };
+      overviewImage: {
+        getCurrentOverviewImage: typeof getCurrentOverviewImage;
+        getOverviewImages: typeof getOverviewImages;
+        hideOverviewImageModal: typeof hideOverviewImageModal;
+        selectOverviewImage: typeof selectOverviewImage;
+        showOverviewImageModal: typeof showOverviewImageModal;
       };
       project: {
         data: {

src/components/FunctionalArea/MapNavigation/MapNavigation.component.test.tsx

 /* eslint-disable no-magic-numbers */
+import { MODELS_MOCK } from '@/redux/compartmentPathways/compartmentPathways.mock';
+import { initialMapDataFixture, openedMapsThreeSubmapsFixture } from '@/redux/map/map.fixtures';
+import { MODELS_DATA_MOCK_WITH_MAIN_MAP } from '@/redux/models/models.mock';
+import { StoreType } from '@/redux/store';
+import { PluginsEventBus } from '@/services/pluginsManager/pluginsEventBus';
 import {
   InitialStoreState,
   getReduxWrapperWithStore,
 } from '@/utils/testing/getReduxWrapperWithStore';
-import { StoreType } from '@/redux/store';
-import { initialMapDataFixture, openedMapsThreeSubmapsFixture } from '@/redux/map/map.fixtures';
 import { act, render, screen, within } from '@testing-library/react';
-import { MODELS_MOCK } from '@/redux/compartmentPathways/compartmentPathways.mock';
-import { MODELS_DATA_MOCK_WITH_MAIN_MAP } from '@/redux/models/models.mock';
-import { PluginsEventBus } from '@/services/pluginsManager/pluginsEventBus';
 import { MapNavigation } from './MapNavigation.component';
 
 const MAIN_MAP_ID = 5053;
@@ -170,7 +170,7 @@ describe('MapNavigation - component', () => {
         histamineMapCloseButton.click();
       });
 
-      expect(dispatchEventMock).toHaveBeenCalledTimes(2);
+      expect(dispatchEventMock).toHaveBeenCalledTimes(4);
       expect(dispatchEventMock).toHaveBeenCalledWith('onSubmapClose', 5052);
       expect(dispatchEventMock).toHaveBeenCalledWith('onSubmapOpen', 52);
     });

src/constants/errors.ts

 export const DEFAULT_ERROR: Error = { message: '', name: '' };
+
+export const OVERVIEW_IMAGE_ERRORS = {
+  IMAGE_ID_IS_INVALID: "Image id is invalid. There's no such image in overview images list",
+};

src/models/pointSchema.ts

+import { z } from 'zod';
+
+export const zPointSchema = z.number().nonnegative('z should be non negative').optional();
+
+export const pointSchema = z.object({
+  x: z.number().nonnegative('x should be non negative'),
+  y: z.number().nonnegative('y should be non negative'),
+  z: zPointSchema,
+});

src/redux/map/map.reducers.ts

 import { DEFAULT_ZOOM } from '@/constants/map';
-import { ActionReducerMapBuilder } from '@reduxjs/toolkit';
 import { PluginsEventBus } from '@/services/pluginsManager/pluginsEventBus';
+import { ActionReducerMapBuilder } from '@reduxjs/toolkit';
 import { getPointMerged } from '../../utils/object/getPointMerged';
 import {
   initMapBackground,
@@ -16,6 +16,7 @@ import {
   SetActiveMapAction,
   SetBackgroundAction,
   SetLastPositionZoomAction,
+  SetLastPositionZoomWithDeltaAction,
   SetMapDataAction,
   SetMapPositionDataAction,
 } from './map.types';
@@ -32,19 +33,34 @@ export const setMapDataReducer = (state: MapState, action: SetMapDataAction): vo
 export const setMapPositionReducer = (state: MapState, action: SetMapPositionDataAction): void => {
   const position = action.payload || {};
   const statePosition = state.data.position;
+  const finalPosition = getPointMerged(position || {}, statePosition.last);
+  const { modelId } = state.data;
+
+  PluginsEventBus.dispatchEvent('onCenterChanged', {
+    modelId,
+    x: finalPosition.x,
+    y: finalPosition.y,
+  });
+
+  if (position?.z) {
+    PluginsEventBus.dispatchEvent('onZoomChanged', {
+      modelId,
+      zoom: position?.z,
+    });
+  }
 
   state.data = {
     ...state.data,
     position: {
-      initial: getPointMerged(position || {}, statePosition.initial),
-      last: getPointMerged(position || {}, statePosition.last),
+      initial: finalPosition,
+      last: finalPosition,
     },
   };
 };
 
 export const varyPositionZoomReducer = (
   state: MapState,
-  action: SetLastPositionZoomAction,
+  action: SetLastPositionZoomWithDeltaAction,
 ): void => {
   const { minZoom, maxZoom } = state.data.size;
   const { delta } = action.payload;
@@ -63,6 +79,23 @@ export const varyPositionZoomReducer = (
   state.data.position.initial.z = newZLimited;
 };
 
+export const setLastPositionZoomReducer = (
+  state: MapState,
+  action: SetLastPositionZoomAction,
+): void => {
+  const { zoom } = action.payload;
+
+  if (state.data.position.last.z !== zoom) {
+    PluginsEventBus.dispatchEvent('onZoomChanged', {
+      modelId: state.data.modelId,
+      zoom,
+    });
+  }
+
+  state.data.position.last.z = zoom;
+  state.data.position.initial.z = zoom;
+};
+
 const updateLastPositionOfCurrentlyActiveMap = (state: MapState): void => {
   const currentMapId = state.data.modelId;
   const currentOpenedMap = state.openedMaps.find(openedMap => openedMap.modelId === currentMapId);

src/redux/map/map.slice.ts

@@ -9,6 +9,7 @@ import {
   initOpenedMapsReducer,
   openMapAndSetActiveReducer,
   setActiveMapReducer,
+  setLastPositionZoomReducer,
   setMapBackgroundReducer,
   setMapDataReducer,
   setMapPositionReducer,
@@ -27,6 +28,7 @@ const mapSlice = createSlice({
     setMapPosition: setMapPositionReducer,
     varyPositionZoom: varyPositionZoomReducer,
     setMapBackground: setMapBackgroundReducer,
+    setLastPositionZoom: setLastPositionZoomReducer,
   },
   extraReducers: builder => {
     initMapPositionReducers(builder);
@@ -45,6 +47,7 @@ export const {
   setMapPosition,
   setMapBackground,
   varyPositionZoom,
+  setLastPositionZoom,
 } = mapSlice.actions;
 
 export default mapSlice.reducer;

src/redux/map/map.types.ts

@@ -88,10 +88,17 @@ export type GetUpdatedMapDataResult = Pick<
 
 export type SetMapPositionDataAction = PayloadAction<Point>;
 
-export type SetLastPositionZoomActionPayload = {
+export type SetLastPositionZoomWithDeltaActionPayload = {
   delta: number;
 };
 
+export type SetLastPositionZoomWithDeltaAction =
+  PayloadAction<SetLastPositionZoomWithDeltaActionPayload>;
+
+export type SetLastPositionZoomActionPayload = {
+  zoom: number;
+};
+
 export type SetLastPositionZoomAction = PayloadAction<SetLastPositionZoomActionPayload>;
 
 export type InitMapDataActionPayload = {

src/services/pluginsManager/map/position/getCenter.test.ts

+import { initialMapDataFixture, openedMapsThreeSubmapsFixture } from '@/redux/map/map.fixtures';
+import { RootState, store } from '@/redux/store';
+import { getCenter } from './getCenter';
+
+jest.mock('../../../../redux/store');
+
+describe('getCenter - plugin method', () => {
+  const getStateSpy = jest.spyOn(store, 'getState');
+
+  getStateSpy.mockImplementation(
+    () =>
+      ({
+        map: {
+          data: {
+            ...initialMapDataFixture,
+            position: {
+              ...initialMapDataFixture.position,
+              last: {
+                x: 2137,
+                y: 420,
+                z: 1.488,
+              },
+            },
+          },
+          loading: 'succeeded',
+          error: { message: '', name: '' },
+          openedMaps: openedMapsThreeSubmapsFixture,
+        },
+      }) as RootState,
+  );
+
+  it('should return last position from Redux', () => {
+    expect(getCenter()).toStrictEqual({
+      x: 2137,
+      y: 420,
+      z: 1.488,
+    });
+  });
+});

src/services/pluginsManager/map/position/getCenter.ts

+import { mapDataLastPositionSelector } from '@/redux/map/map.selectors';
+import { store } from '@/redux/store';
+import { Point } from '@/types/map';
+
+export const getCenter = (): Point => {
+  const { getState } = store;
+  const lastPosition = mapDataLastPositionSelector(getState());
+
+  return lastPosition;
+};

src/services/pluginsManager/map/position/setCenter.test.ts

+import { setMapPosition } from '@/redux/map/map.slice';
+import { store } from '@/redux/store';
+import { Point } from '@/types/map';
+import { ZodError } from 'zod';
+import { setCenter } from './setCenter';
+
+jest.mock('../../../../redux/store');
+
+describe('setCenter - plugin method', () => {
+  const dispatchSpy = jest.spyOn(store, 'dispatch');
+
+  describe('when position is invalid', () => {
+    const invalidPositions = [
+      {
+        x: -1,
+        y: 1,
+        z: 1,
+      },
+      {
+        x: 1,
+        y: -1,
+        z: 1,
+      },
+      {
+        x: 1,
+        y: 1,
+        z: -1,
+      },
+      {
+        y: 1,
+      },
+      {
+        x: 1,
+      },
+    ] as Point[];
+
+    it.each(invalidPositions)('should throw error', position => {
+      expect(() => setCenter(position)).toThrow(ZodError);
+    });
+  });
+
+  describe('when position is valid', () => {
+    const position: Point = {
+      x: 500,
+      y: 200,
+      z: 2,
+    };
+
+    it('should set map position', () => {
+      setCenter(position);
+
+      expect(dispatchSpy).toHaveBeenCalledWith(setMapPosition(position));
+    });
+  });
+});

src/services/pluginsManager/map/position/setCenter.ts

+import { pointSchema } from '@/models/pointSchema';
+import { setMapPosition } from '@/redux/map/map.slice';
+import { store } from '@/redux/store';
+import { Point } from '@/types/map';
+
+export const setCenter = (position: Point): void => {
+  const { dispatch } = store;
+  pointSchema.parse(position);
+
+  dispatch(setMapPosition(position));
+};

src/services/pluginsManager/map/zoom/getZoom.test.ts

+/* eslint-disable no-magic-numbers */
+import { initialMapDataFixture, openedMapsThreeSubmapsFixture } from '@/redux/map/map.fixtures';
+import { RootState, store } from '@/redux/store';
+import { getZoom } from './getZoom';
+
+jest.mock('../../../../redux/store');
+
+describe('getZoom - plugin method', () => {
+  const getStateSpy = jest.spyOn(store, 'getState');
+
+  describe('when last position zoom is present', () => {
+    beforeEach(() => {
+      getStateSpy.mockImplementation(
+        () =>
+          ({
+            map: {
+              data: {
+                ...initialMapDataFixture,
+                position: {
+                  ...initialMapDataFixture.position,
+                  last: {
+                    x: 2137,
+                    y: 420,
+                    z: 1.488,
+                  },
+                },
+              },
+              loading: 'succeeded',
+              error: { message: '', name: '' },
+              openedMaps: openedMapsThreeSubmapsFixture,
+            },
+          }) as RootState,
+      );
+    });
+
+    it('should return last position from Redux', () => {
+      expect(getZoom()).toEqual(1.488);
+    });
+  });
+
+  describe('when last position zoom is NOT present', () => {
+    beforeEach(() => {
+      getStateSpy.mockImplementation(
+        () =>
+          ({
+            map: {
+              data: {
+                ...initialMapDataFixture,
+                position: {
+                  ...initialMapDataFixture.position,
+                  last: {
+                    x: 2137,
+                    y: 420,
+                  },
+                },
+              },
+              loading: 'succeeded',
+              error: { message: '', name: '' },
+              openedMaps: openedMapsThreeSubmapsFixture,
+            },
+          }) as RootState,
+      );
+    });
+
+    it('should return undefined', () => {
+      expect(getZoom()).toBeUndefined();
+    });
+  });
+});

src/services/pluginsManager/map/zoom/getZoom.ts

+import { mapDataLastPositionSelector } from '@/redux/map/map.selectors';
+import { store } from '@/redux/store';
+
+export const getZoom = (): number | undefined => {
+  const { getState } = store;
+  const lastPosition = mapDataLastPositionSelector(getState());
+
+  return lastPosition?.z;
+};

src/services/pluginsManager/map/zoom/setZoom.test.ts

+/* eslint-disable no-magic-numbers */
+import { setLastPositionZoom } from '@/redux/map/map.slice';
+import { store } from '@/redux/store';
+import { ZodError } from 'zod';
+import { setZoom } from './setZoom';
+
+jest.mock('../../../../redux/store');
+
+describe('setZoom - plugin method', () => {
+  const dispatchSpy = jest.spyOn(store, 'dispatch');
+
+  describe('when zoom is invalid', () => {
+    const invalidZoom = [-1, -123, '-123'] as number[];
+
+    it.each(invalidZoom)('should throw error', zoom => {
+      expect(() => setZoom(zoom)).toThrow(ZodError);
+    });
+  });
+
+  describe('when zoom is valid', () => {
+    const zoom = 2;
+
+    it('should set map zoom', () => {
+      setZoom(zoom);
+
+      expect(dispatchSpy).toHaveBeenCalledWith(setLastPositionZoom({ zoom }));
+    });
+  });
+});

src/services/pluginsManager/map/zoom/setZoom.ts

+import { zPointSchema } from '@/models/pointSchema';
+import { setLastPositionZoom } from '@/redux/map/map.slice';
+import { store } from '@/redux/store';
+
+export const setZoom = (zoom: number): void => {
+  const { dispatch } = store;
+  zPointSchema.parse(zoom);
+
+  dispatch(setLastPositionZoom({ zoom }));
+};

src/services/pluginsManager/overviewImage/getCurrentOverviewImage.ts

+import { currentOverviewImageSelector } from '@/redux/project/project.selectors';
+import { store } from '@/redux/store';
+import { OverviewImageView } from '@/types/models';
+
+export const getCurrentOverviewImage = (): OverviewImageView | undefined => {
+  const { getState } = store;
+  const overviewImage = currentOverviewImageSelector(getState());
+
+  return overviewImage;
+};