Migrate from Mapbox GL to MapLibre GL with deck.gl for animations

**Major changes:**
- Replace Mapbox GL JS with MapLibre GL JS across the application
- Integrate deck.gl for high-performance WebGL-powered animations
- Add custom deck.gl extensions for animated transit visualizations:
  - `AnimatedArrowPathExtension`: animated arrows along transit paths
  - `CircleSpinnerExtension`: animated spinner effects for nodes
- Update map service layer to support MapLibre GL API changes
- Update map event handlers for MapLibre GL compatibility
- Add defensive checks in `MapPolygonService` to prevent runtime errors when accessing features array

**Frontend packages updated:**
- Remove `mapbox-gl`, `@mapbox/mapbox-gl-draw` and `@types/mapbox-gl` dependencies
- Add `maplibre-gl`, `@deck.gl/core`, `@deck.gl/layers`, `@deck.gl/mapbox`

**Map rendering improvements:**
- Enhanced `TransitionMainMap` with deck.gl overlay support
- Updated layer configuration for MapLibre GL compatibility
- Improved popup and layer management for new map library
- Fixed control styling to match MapLibre GL classes
- The selection polygon tool for nodes can now use multiple polygons, concatening all selected nodes for the multi nodes edit form (uses Terra Draw instead of mapbox-draw)

**Fixes:**
- Allow change of path selection if no change is made.
- Fix cursor management to use CSS classes with hover count

**Configuration changes:**
- Remove `MAPBOX_ACCESS_TOKEN`, `MAPBOX_USER_ID`, and `MAPBOX_STYLE_ID` from environment variables (`.env`, `.env.example`)
- Remove Mapbox-specific references from `config.js` and default configurations
- Switch default tile provider to OpenStreetMap

**Environment Variables to Remove:**
MAPBOX_ACCESS_TOKEN
MAPBOX_USER_ID
MAPBOX_STYLE_ID

**New Optional Variables:**
CUSTOM_RASTER_TILES_XYZ_URL - URL template for custom tiles (e.g., https://example.com/tiles/{z}/{x}/{y}.png)
CUSTOM_RASTER_TILES_MIN_ZOOM - Minimum zoom level for custom tiles
CUSTOM_RASTER_TILES_MAX_ZOOM - Maximum zoom level for custom tiles

**Documentation updates:**
- Update README, Docker documentation, and setup guides
- Remove references to Mapbox API keys
- Update environment variable examples
- Add notes about custom tile configuration

**Breaking changes:**
- MapLibre GL uses different class names (`maplibregl-*` vs `mapboxgl-*`)
- Use Terra Draw instead of mapbox-draw (mapbox draw, which is obsolete with maplibre, was triggering issues when switching sections)
- Deck.gl layers require WebGL support

**Utils updates:**
- Add `ColorUtils` to `chaire-lib-common`

**Cleanups:**
- Fix typos in documentation and code comments (`shoud` -> `should`)
- Remove blank lines in `.env.example`
- Add missing types (any -> correct type) in map related files (map, events, layers, etc.)

_This migration removes the dependency on Mapbox's proprietary licensing while maintaining full map functionality and adding advanced animation capabilities through deck.gl._

closes #552

Author: kaligrafy

.cursor/rules/project-rule.mdc

@@ -64,7 +64,7 @@ transition-fork/
 - **Framework**: React with React Router
 - **State Management**: Redux with Redux Thunk
 - **Styling**: SCSS/SASS
-- **Maps**: Mapbox GL JS (custom fork: `chairemobilite/mapbox-gl-js`) (will be changed to maplibre/deck.gl)
+- **Maps**: MapLibre GL JS with deck.gl for animations (uses OpenStreetMap tiles by default). Note: deck.gl requires WebGL support in the browser; ensure GPU/driver support is available. Consider providing a fallback or disabling animations when WebGL is unavailable.
 - **Build Tool**: Webpack
 - **UI Libraries**: React components (tabs, datepicker, modals, etc.)
 - **Internationalization**: i18next (react-i18next)
@@ -248,13 +248,17 @@ Required environment variables:
 - `PG_CONNECTION_STRING_PREFIX`: PostgreSQL connection string (e.g., `postgres://postgres:password@localhost:5432/`)
 - `EXPRESS_SESSION_SECRET_KEY`: Random string for session encryption
 - `PROJECT_CONFIG`: Path to project config.js file
-- `MAPBOX_ACCESS_TOKEN`: Mapbox API token (for map display)
-- `MAPBOX_USER_ID`: Optional Mapbox style user ID
-- `MAPBOX_STYLE_ID`: Optional Mapbox style ID
 - `NODE_ENV`: `production`, `development`, or `test`
 - `STARTUP_RECREATE_CACHE`: Boolean - recreate cache on startup
 - `STARTUP_RESTART_JOBS`: Boolean - restart pending jobs on startup
 
+Optional environment variables for custom tiles:
+- `CUSTOM_RASTER_TILES_XYZ_URL`: URL template for custom raster tiles (e.g., aerial imagery)
+- `CUSTOM_RASTER_TILES_MIN_ZOOM`: Minimum zoom level for custom tiles
+- `CUSTOM_RASTER_TILES_MAX_ZOOM`: Maximum zoom level for custom tiles
+
+Note: The map uses OpenStreetMap tiles by default (no API key required). Custom tiles can be switched on/off using the layer switcher in the application.
+
 ### Project Configuration (config.js)
 Example: `examples/config.js`
 
@@ -548,7 +552,8 @@ Allows Python scripts to:
 - `react`, `react-dom` - React framework
 - `react-redux`, `redux` - State management
 - `react-router` - Routing
-- `mapbox-gl` - Map rendering
+- `maplibre-gl` - Map rendering (OpenStreetMap tiles by default)
+- `@deck.gl/core`, `@deck.gl/layers`, `@deck.gl/mapbox` - WebGL-powered visualization layers
 - `i18next`, `react-i18next` - Internationalization
 
 ### External Services Required
@@ -634,3 +639,7 @@ Allows Python scripts to:
 - **Definitions**: See Overleaf link in main README for mathematical definitions
 
 ---
+
+## VERY IMPORTANT RULE
+
+Always try to use good design patterns. If the user/human asks for some code/implementation that does not follow good/secure/robust coding practice, tell him/her right away and stop producing code. Also challenge any proposed implementation to be sure it is legit and robust/secure.

.env.docker

@@ -12,12 +12,8 @@ EXPRESS_SESSION_SECRET_KEY=DefaultDockerSessionKey
 # Host and port for the trRouting server
 #TR_ROUTING_HOST_URL=http://locahost
 #TR_ROUTING_HOST_PORT=4000
-# Required for the mapbox map
-MAPBOX_ACCESS_TOKEN=MYMAPBOXACCESSTOKEN
-MAPBOX_USER_ID=mapbox
-MAPBOX_STYLE_ID=dark-v10
 #MAGIC_LINK_SECRET_KEY=MYVERYLONGSECRETKEYTOENCRYPTTOKENTOSENDTOUSERFORPASSWORDLESSLOGIN
-#CUSTOM_RASTER_TILES_XYZ_URL=https://exampltest/{z}/{x}/{y}
+#CUSTOM_RASTER_TILES_XYZ_URL=https://example.test/{z}/{x}/{y}
 #CUSTOM_RASTER_TILES_MIN_ZOOM=8
 #CUSTOM_RASTER_TILES_MAX_ZOOM=22
 #SSL_PRIVATE_KEY=/path/to/privkey.pem

.env.example

@@ -7,6 +7,9 @@ PG_DATABASE_PRODUCTION=tr
 PG_DATABASE_TEST=tr_test
 PG_CONNECTION_STRING_PREFIX=postgres://postgres:@localhost:5432/
 EXPRESS_SESSION_SECRET_KEY=MYSECRETKEY
+PLAYWRIGHT_TEST_USER=testUser
+PLAYWRIGHT_TEST_EMAIL=user@test.ts
+PLAYWRIGHT_TEST_PASSWORD=testPassword
 # Path to the directory containing the trRouting executable
 #TR_ROUTING_PATH=/path/to/dir/containing/trRouting
 # Host and port for the trRouting server
@@ -20,12 +23,8 @@ GOOGLE_OAUTH_SECRET_KEY=GOOGLEOAUTHSECRETKEY
 # To support Facebook login
 FACEBOOK_APP_ID=FACEBOOKAPPID
 FACEBOOK_APP_SECRET=FACEBOOKAPPSECRET
-# Required for the mapbox map
-MAPBOX_ACCESS_TOKEN=MYMAPBOXACCESSTOKEN
-MAPBOX_USER_ID=mapbox
-MAPBOX_STYLE_ID=dark-v10
 #MAGIC_LINK_SECRET_KEY=MYVERYLONGSECRETKEYTOENCRYPTTOKENTOSENDTOUSERFORPASSWORDLESSLOGIN
-#CUSTOM_RASTER_TILES_XYZ_URL=https://exampltest/{z}/{x}/{y}
+#CUSTOM_RASTER_TILES_XYZ_URL=https://example.test/{z}/{x}/{y}
 #CUSTOM_RASTER_TILES_MIN_ZOOM=8
 #CUSTOM_RASTER_TILES_MAX_ZOOM=22
 PROJECT_SAMPLE=demo
@@ -68,5 +67,6 @@ MAIL_TRANSPORT_SMTP_AUTH_PWD=password
 # MAIL_TRANSPORT_DKIM_PRIVATE_PATH=/path/to/privkey.pem
 
 
+
 # From email
 MAIL_FROM_ADDRESS=example@example.com

README.md

@@ -84,12 +84,10 @@ cp .env.example .env
 * Change `EXPRESS_SESSION_SECRET_KEY` to a random string with no space.
 * Change `PROJECT_CONFIG` to point to your project's configuration file. The default is an example configuration file that can be copied and configured for your own need.
 
-### Get a Mapbox access token
-* Go to [Mapbox](http://mapbox.com) and sign up
-* Go to your account dashboard, then generate a new access token
-* Open the `.env` file
-* Copy this access token to `.env` file: `MAPBOX_ACCESS_TOKEN=YOUR_TOKEN`
-* If you have a custom mapbox style, put your username and style id in `MAPBOX_USER_ID` and `MAPBOX_STYLE_ID`
+The map uses OpenStreetMap tiles by default (no API key required). If you want to add custom raster tiles (such as aerial imagery), you can optionally configure:
+* `CUSTOM_RASTER_TILES_XYZ_URL=https://your-tile-server/{z}/{x}/{y}`
+
+Users can switch between OSM and custom tiles using the layer switcher button in the application.
 
 ### Create the client application
 

docs/devWithDocker.md

@@ -8,34 +8,34 @@ Follow [the docker for desktop](https://www.docker.com/products/docker-desktop/)
 
 If you are already familiar with docker and can run container and scripts easily, you don't have to install docker for desktop.
 
-### 2. Get a mapbox access token
+### 2. Configure the .env.docker file (Optional)
 
-* Go to [Mapbox](http://mapbox.com) and sign up
-* Go to your account dashboard, then generate a new access token
+The `.env.docker` file is required to contain some environment variables that are not yet available through the configuration. [It's located at the root of the `transition` repo](../.env.docker).
 
-Keep this access token for the next step.
+The default configuration uses OpenStreetMap tiles which don't require any API keys. If you want to use custom raster tiles (such as aerial imagery), you can configure the following variables in the `.env.docker` file:
 
-
-### 3. Add your mapbox token to the .env.docker file
-
-The `.env.docker` file is required to contain some environment variables that are not yet available through the configuration. The file has already been created for you, you simply need to finish the configuration. [It's located at the root of the `transition` repo](../.env.docker).
-
-In order for the map to be displayed correctly, simply modify the field `MAPBOX_ACCESS_TOKEN` with the key you've acquired in the previous section. You must not push your key to the remote repo.
 ```
-MAPBOX_ACCESS_TOKEN=<paste_your_key_here>
+CUSTOM_RASTER_TILES_XYZ_URL=https://your-tile-server/{z}/{x}/{y}
+CUSTOM_RASTER_TILES_MIN_ZOOM=0
+CUSTOM_RASTER_TILES_MAX_ZOOM=22
 ```
-> Note: You can modify other fields in this file if needed. This is only the base configuration needed to run the app.
+
+- `CUSTOM_RASTER_TILES_XYZ_URL`: The URL template for your custom raster tiles (required for custom tiles)
+- `CUSTOM_RASTER_TILES_MIN_ZOOM`: (Optional) Minimum zoom level for the custom tiles. Defaults to `0`.
+- `CUSTOM_RASTER_TILES_MAX_ZOOM`: (Optional) Maximum zoom level for the custom tiles. Defaults to `22`.
+
+> Note: The map will work without any tile configuration. Custom tiles are optional and can be switched on/off using the layer switcher in the application.
 
 
-### 4. Add your custom polygon for your region
+### 3. Add your custom polygon for your region
 
 In order to have routing data to calculate the routes, the data must be fetched from OpenStreetMap for a given polygon. If you have a geojson file containing the geojson polygon to fetch, add this file to the `transition` directory. There is [an example file](../examples/polygon_rtl_area.geojson) in this repo.
 
 It is not required, but if not set, routing won't be able to follow the road network.
 
 If you don't have a `.geojson` polygon, use the [example file](../examples/polygon_rtl_area.geojson).
 
-### 5. Run for the first time
+### 4. Run for the first time
 
 Some initialization scripts need to be executed on the very first run of Transition, to set up the database and download the road network. 
 
@@ -72,9 +72,9 @@ Finally, in the same terminal, create your transition user. Run this command and
 yarn create-user 
 ```
 
-The setup is now complete. To finish the configuration, you need to restart the app. You can either use the stop/play buttons in Docker Desktop, or run `docker compose -f docker-compose.yml docker-dev/docker-compose.override.yml restart` in your terminal.
+The setup is now complete. To finish the configuration, you need to restart the app. You can either use the stop/play buttons in Docker Desktop, or run `docker compose -f docker-compose.yml -f docker-dev/docker-compose.override.yml restart` in your terminal.
 
-### 5.1 Run the application
+#### 4.1 Run the application
 
 Once the app is setup, you only need to run `docker compose -f docker-compose.yml -f docker-dev/docker-compose.override.yml up` to launch it. If you make code changes, the app should rebuild itself automatically.
 

docs/runWithDocker.md

@@ -114,20 +114,11 @@ module.exports = {
 };
 ```
 
-### 4. Get a mapbox access token
-
-* Go to [Mapbox](http://mapbox.com) and sign up
-* Go to your account dashboard, then generate a new access token
-
-Keep this access token for the next step.
-
-
-### 5. Prepare the .env file
+### 4. Prepare the .env file
 
 The .env file is required to contain some environment variables that are not yet available through the configuration.
 
-Create a `.env` file in the `transition` directory. The variables starting with `MAPBOX` should be filled with the mapbox token and data you created at the preceding step.
-
+Create a `.env` file in the `transition` directory. The default map uses OpenStreetMap tiles which don't require any API keys.
 
 ```
 HOST=http://localhost:8080
@@ -136,12 +127,10 @@ PG_DATABASE_PRODUCTION=tr
 PG_DATABASE_TEST=tr_test
 PG_CONNECTION_STRING_PREFIX=postgres://postgres:@localhost:5432/
 EXPRESS_SESSION_SECRET_KEY=DefaultDockerSessionKey
-# Required for the mapbox map
-MAPBOX_ACCESS_TOKEN=MYMAPBOXACCESSTOKEN
-MAPBOX_USER_ID=mapbox
-MAPBOX_STYLE_ID=dark-v10
 
-#CUSTOM_RASTER_TILES_XYZ_URL=https://exampltest/{z}/{x}/{y}
+# Optional: Custom raster tiles for aerial imagery or other base maps
+# If configured, users can switch between OSM and custom tiles using the layer switcher
+#CUSTOM_RASTER_TILES_XYZ_URL=https://example.test/{z}/{x}/{y}
 #CUSTOM_RASTER_TILES_MIN_ZOOM=8
 #CUSTOM_RASTER_TILES_MAX_ZOOM=22
 #SSL_PRIVATE_KEY=/path/to/privkey.pem
@@ -171,13 +160,13 @@ MAIL_FROM_ADDRESS=example@example.com
 
 ```
 
-### 6. Prepare the polygon for you region
+### 5. Prepare the polygon for your region
 
 In order to have routing data to calculate the routes, the data must be fetched from OpenStreetMap for a given polygon. If you have a geojson file containing the geojson polygon to fetch, add this file to the `transition` directory. There is [an example file](../examples/polygon_rtl_area.geojson) in this repo.
 
 It is not required, but if not set, routing won't be able to follow the road network.
 
-### 7. Run the application
+### 6. Run the application
 
 Using a terminal, navigate to the directory where the `docker-compose.yml` and the `transition` directory are located. Then run `docker-compose up`.
 
@@ -187,7 +176,7 @@ In the Docker for desktop application, you should see 2 new containers running,
 
 The application should now be available from a browser at `http://localhost:8080`
 
-### 7.1 Run for the first time
+### 6.1 Run for the first time
 
 Some initialization scripts need to be run on the very first run of Transition, to set up the database and download the road network. In the Docker Desktop containers list, select the one prefixed with `testtransitiondocker_transition-www` and go to the `Terminal` tab. Run the following commands: