Documentation added + codebase cleanup

CONTRIBUTING.md

@@ -367,6 +367,63 @@ English deck), listed in order of priority:
 - **[Den Store Danske](https://denstoredanske.lex.dk/)** - Denmarks national encyclopedia.
 - **[Wikipedia in Danish](https://da.wikipedia.org)** - Used when neither of the above sources where enough to verify spelling.
 
+## Experimental deck
+
+### Glossary
+
+- Interactive map - SVG canvas of a world (or other region) map that responds to user manipulations (i.e. dragging, scrolling, swiping), aiding the user in visual region recognition
+
+### Overview
+
+The sole intention of the deck is "incubating" the idea of interactive map for various note templates (currently Country - Map only).
+
+Note, that logic behind interactive map:
+-  was developed with flexibility in mind, meaning that it is highly customizable (see [Configuration](#Configuration) section)
+- follows robustness principle, meaning any misconfiguration, script loading failure or other error will not lead to the deck becoming unusable, but rather will make the deck default to the behaviour of extended version up until the initial issue is resolved
+
+### File structure
+
+- `_jsvectormap.js`, `_jsvectormap.min.css` - the code and styling of the underlying library using which the interactive map is implemented
+- `_world.js` - definition of SVG map in the library-compatible format
+- `_interactive_map_config.js` - various configurations used by the program
+- `_interactive_map_init.js` - the basis of the logic where preparatory steps and interactive map initialization take place
+
+Note that `_interactive_map_init.js` file is written with readability in mind (i.e. self-documented function and variable names, function docs), thus rendering any additional documentation useless due to providing essentially no supplementary information.
+
+### Configuration
+
+Customizable configuration is defined in `_interactive_map_config.js` script of user's `collection.media` folder. Note that only `getUserConfig()` function return object may be edited and modification of any other option may lead to unexpected outcome.
+
+The configuration consists of 2 self-descriptive parts:
+
+- `commonFeatures`:
+  - `interactiveEnabled` - switch to set interactive map on/off. May be used in case of critical bugs discovery to roll back to extended deck version behaviour
+  - `interactiveMobileEnabled` - switch to control interactive map mode for mobile (both AnkiDroid and Anki Mobile). Note that when `interactiveEnabled` is `false` the option is ignored
+  - `autoAnswerEnabled` - switch to define whether a card is automatically swapped to answer side after the user selects a region
+  - `toolTipEnabled` - a tooltip showing region name on answer card side on hover. Note that by default the feature is disabled as it is unclear of its consequences on remembering process - user might use it as a hint to show region name represented by a card further in the review queue
+- `commonColors`
+  - `region`, `selectedRegion`, `incorrectRegionHighlight`, `correctRegionHighlight` - region colors in various states
+  - `background` - map background that is by default blue to create appearance of water mass
+  - `border` - region border color
+  - `tooltipBackground`, `tooltipText` - tooltip colors
+
+Note that any misconfiguration of the aforementioned properties will lead to the program defaulting to initial values. For example `fasle` string for any of the `commonFeatures` properties or `red` for any of `commonColors`.
+
+### AnkiDroid notice
+
+When using interactive map on AnkiDroid be sure to either:
+
+- Disable gestures when reviewing the note templates including the map (e.g. disabling gestures and using filtered deck to review the cards)
+- Disable interactive map on mobile via `interactiveMobileEnabled` option in the [configuration](#Configuration)
+
+Note that enabled gestures do not in any way break interactive map logic, so if the user finds a way of working with both enabled, then there should not be any issues. The recommendation is written purely for practical reasons as usage of the one feature may lead to accidental interaction with the other.
+
+### Implementation decision notices
+
+- `_interactive_map_init.js` script is wrapped around IIFE due to Anki web view being persistent for card reviews meaning that writing `let a = 1` in global scope leads to failure due to redeclaration of the variable (and using `var` is generally considered a bad practice due to polluting the global namespace, though succeeding to work)
+- `value--image` element in note template corresponding to the static map fallback is intentionally left unchanged while `value--map` (corresponding to interactive map) is initially set to `display: none` in order to accommodate scripts loading failure situations
+- `swapToBackSide()` function that performs automatic swap to answer card side heavily relies on Anki APIs support for which may be removed at any moment. Thus, such feature might not be considered reliable and in the worst case scenario its existence might be deprecated while interactive map still working as usual, simply without it
+
 ## Maintainer's guide
 
 ### Versioning

README.md

@@ -31,7 +31,7 @@ The deck is available in **English**, **German**, **Spanish**, **French**, **Nor
 
 ## Features
 
-The standard version of the deck comes with four note templates: _Country - Capital_, _Capital - Country_, _Flag - Country_, and _Map - Country_. An **extended version** is also available, with two additional note templates: _Country - Flag_ and _Country - Map_.
+The standard version of the deck comes with four note templates: _Country - Capital_, _Capital - Country_, _Flag - Country_, and _Map - Country_. An **extended version** is also available, with two additional note templates: _Country - Flag_ and _Country - Map_. The **experimental version** is a clone of extended version except it also provides interactivity for the _Country - Map_ note template.
 
 <table>
   <tr><th scope="col" colspan="2">Flag - Country</th></tr>
@@ -103,9 +103,10 @@ In order to install and later upgrade _Ultimate Geography_, you'll need to first
 You're now ready to install _Ultimate Geography_:
 
 1. Go to the **[_Releases_ page](https://github.com/anki-geo/ultimate-geography/releases)**.
-1. In the latest release's _Assets_ section, download the ZIP archive of the version of the deck you'd like to use. You can choose between [a standard and an extended version](#features) in a number of [languages](#ultimate-geography) -- for instance, if you're after the standard German deck, download `Ultimate_Geography_v[...]_DE.zip`.
+1. In the latest release's _Assets_ section, download the ZIP archive of the version of the deck you'd like to use. You can choose between [a standard, extended and experimental version](#features) in a number of [languages](#ultimate-geography) -- for instance, if you're after the standard German deck, download `Ultimate_Geography_v[...]_DE.zip`.
 1. Extract the content of the archive on your computer.
 1. Open Anki and make sure your devices are all synchronised.
+1. Create [a backup](https://docs.ankiweb.net/backups.html) via "File -> Create Backup" option to be able to roll back in case something goes wrong
 1. In the _File_ menu, select _CrowdAnki: Import from disk_.
 1. Browse for and select the folder you extracted from the archive, which contains the deck's JSON file and `media` folder -- e.g. `Ultimate Geography [DE]`.
 1. Don't change anything in the _CrowdAnki Import Settings_ dialog box that opens -- just press _OK_ to start the import. A dialog box should then confirm that the import was successful.

src/media/experimental_assets/_interactive_map_init.js

@@ -1,4 +1,3 @@
-// IIFE is used intentionally to isolate namespaces between cards of a review session
 (function () {
   const mapConfig = getMapConfig();
   const commonConfig = mapConfig.commonConfig;
@@ -25,7 +24,7 @@
 
 
   /**
-   * Using configuration options determine whether to display interactive map
+   * Using configuration options to determine whether to display interactive map
    */
   function resolveInteractiveEnabled() {
     return commonConfig.interactiveEnabled && (nonMobile() || interactiveMobileEnabled())
@@ -55,6 +54,11 @@
     commonElements.interactiveMap.style.display = enabled ? "block" : "none";
   }
 
+  /**
+   * Determine card side using predefined names from configuration.
+   * Note that current card side is figured out via accessing the value of
+   * data attribute of the <script> element invoking the program
+   */
   function cardSide(cardSideName) {
     return commonConfig.cardSide === cardSideName;
   }
@@ -85,7 +89,7 @@
 
       onRegionSelected: swapToBackSide,
 
-      ...mobileDraggingHack(false)
+      ...mobileSwipingHack(false)
     });
   }
 
@@ -99,14 +103,14 @@
 
       regionStyle: {
         ...commonMap.regionStyle,
-        selected: {fill: getGreenRedRegionColor()}
+        selected: {fill: getRegionColor()}
       },
       focusOn: {
         region: commonConfig.regionCode,
         animate: true
       },
 
-      ...mobileDraggingHack(commonConfig.toolTipEnabled, (event, tooltip) => {
+      ...mobileSwipingHack(commonConfig.toolTipEnabled, (event, tooltip) => {
         tooltip._tooltip.style.backgroundColor = commonColors.tooltipBackground;
         tooltip._tooltip.style.color = commonColors.tooltipText;
       })
@@ -123,11 +127,11 @@
   }
 
   /**
-   * Jsvectormap library bug - map dragging does not work on mobile with disabled tooltip.
+   * Jsvectormap library bug - map swiping does not work on mobile with disabled tooltip.
    * Enable tooltip and hide it in case original tooltip is not displayable.
    * Current handling is temporary fix until library issue is resolved
    */
-  function mobileDraggingHack(tooltipEnabled, tooltipShowHandler) {
+  function mobileSwipingHack(tooltipEnabled, tooltipShowHandler) {
     return commonConfig.isMobile
       ? {
         showTooltip: true,
@@ -167,10 +171,10 @@
 
   /**
    * Retrieve region highlighting color for answer card side
-   * @returns {string} - Green hex code if and only if green highlighting
-   * mode is enabled and region is selected correctly, red hex code otherwise
+   * depending on the configuration and whether the selected
+   * by the user on question side region is correct
    */
-  function getGreenRedRegionColor() {
+  function getRegionColor() {
     return commonConfig.regionCode === sessionStorage.getItem(commonConfig.selectedRegionSessionKey)
       ? commonColors.correctRegionHighlight
       : commonColors.incorrectRegionHighlight;