linuxmint · guillaume-mueller · Nov 2, 2025 · Nov 2, 2025 · Nov 2, 2025 · Nov 2, 2025
diff --git a/auto-dark-light@gihaume/.editorconfig b/auto-dark-light@gihaume/.editorconfig
@@ -0,0 +1,9 @@
+[*.*]
+charset = utf-8
+indent_size = 4
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+trim_final_newline = true
+end_of_line = lf
+max_line_length = 80
diff --git a/auto-dark-light@gihaume/.gitignore b/auto-dark-light@gihaume/.gitignore
@@ -0,0 +1,3 @@
+node_modules
+.pnpm-store
+.venv
diff --git a/auto-dark-light@gihaume/.vscode/extensions.json b/auto-dark-light@gihaume/.vscode/extensions.json
@@ -0,0 +1,8 @@
+{
+    "recommendations": [
+        "EditorConfig.EditorConfig",
+        "ms-python.python",
+        "pkief.material-icon-theme",
+        "vitest.explorer"
+    ]
+}
diff --git a/auto-dark-light@gihaume/.vscode/settings.json b/auto-dark-light@gihaume/.vscode/settings.json
@@ -0,0 +1,8 @@
+{
+    "typescript.tsdk": "node_modules/typescript/lib",
+    "python.analysis.extraPaths": [
+        "/usr/share/cinnamon/cinnamon-settings/bin"
+    ],
+    "javascript.preferences.quoteStyle": "single", // For imports autocompletion
+    "typescript.preferences.quoteStyle": "single" // For imports autocompletion
+}
diff --git a/auto-dark-light@gihaume/CHANGELOG.md b/auto-dark-light@gihaume/CHANGELOG.md
@@ -1,45 +1,104 @@
-## 1.2.6 - 18.05.2025
+# Changelog
 
-- Corrected commands launching not supporting `;` in the command
+The format adheres to [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/) and [SemVer 2.0.0](https://semver.org/spec/v2.0.0.html)
 
-## 1.2.5 - 18.05.2025
+## [2.0.0] - 2025-11-02 - [#7939](https://github.com/linuxmint/cinnamon-spices-applets/pull/7939)
 
-- Corrected `g++` dependancy wrongly verified as `gcc`
-- Added explicit notification for not supported versions of Cinnamon
+Extensive rewrite to enable new features – some bugs may have been introduced.
 
-## 1.2.4 - 13.05.2025
+### Added
 
-- Added TypeScript checks via `jsconfig.json`
-- Renamed a lot of things
+- Manual switching schedule per twilight ([#6758](https://github.com/linuxmint/cinnamon-spices-applets/issues/6758)).
+- Automatic switching schedule offset per twilight ([#7247](https://github.com/linuxmint/cinnamon-spices-applets/issues/7247)).
+- Keybinding to toggle appearance ([#7923](https://github.com/linuxmint/cinnamon-spices-applets/issues/7923)).
+- Indicator showing if the actual appearance is unsynced with the current time, also in the settings configure menu (previously only shown in the panel's icon state).
+- Indicator of the next appearance update schedule.
+- Indicator of the twilights computed from the location as a widget instead of the previous notification triggered from a button.
+- Indicator of the current system location.
+- **Known limitation**: some indicators are updated with a delay of 2 seconds because of an [issue with Cinnamon's settings](https://github.com/linuxmint/cinnamon/issues/12362).
 
-## 1.2.3 - 28.04.2025
+### Changed
 
-- Background handling feature:
-  - Corrected applying both file and folder while it should only do one at once
-  - Added support for non-ASCII URIs
+- Every previous "mode" textual reference to be "appearance".
+- Themes fields to be read-only.
+- Timezone coordinates local database to be the same as the ones used by Cinnamon Settings Daemon's Night Light.
+  - Note that there can still be a difference in the twilight times as their calculation is done differently.
+- Improvement of logging and notifications types for better look and clarity.
 
-## 1.2.2 - 23.01.2025
+### Changed (internal)
 
-- Added missing import in `time_change_listener/main.cpp` for GCC 14.2
+- Use of MobX for scalable reactive state management.
+- Use of Vite transpilation for better imports handling, use of external libraries and bundling.
+- Use of TypeScript for more concise typing.
+- Use of Vitest for unit testing.
+- Replacement of the C++ wall-clock adjustment (passive) listener for a simpler JavaScript monitor counterpart (active polling).
 
-## 1.2.1 - 22.10.2024
+## [1.2.6] - 2025-05-18 - [#7257](https://github.com/linuxmint/cinnamon-spices-applets/pull/7257)
 
-- Custom commands launching feature:
-  - Corrected list's `Active` attribute default to `true`
-  - Added shell features support
+### Fixed
 
-## 1.2.0 - 22.10.2024
+- Custom commands launching to correctly support `;` shell feature. [#6549](https://github.com/linuxmint/cinnamon-spices-applets/issues/6549)
 
-- Added custom commands launching feature
+## [1.2.5] - 2025-05-18 - [#7256](https://github.com/linuxmint/cinnamon-spices-applets/pull/7256)
 
-## 1.1.0 - 02.09.2024
+### Added
 
-- Added desktop background support
+- Explicit notification for not supported versions of Cinnamon ([#7207](https://github.com/linuxmint/cinnamon-spices-applets/issues/7207)).
 
-## 1.0.1 - 26.08.2024
+### Fixed
 
-- Replaced `DateTime` methods incompatible with `GLib` < 2.80
+- `g++` dependency wrongly verified as `gcc`.
 
-## 1.0.0 - 26.08.2024
+## [1.2.4] - 2025-05-13 - [#7217](https://github.com/linuxmint/cinnamon-spices-applets/pull/7217)
+
+### Changed (internal)
+
+- Use of TypeScript checking via JSDoc.
+- Renaming of a lot of code things.
+
+## [1.2.3] - 2025-04-28 - [#7140](https://github.com/linuxmint/cinnamon-spices-applets/pull/7140)
+
+### Fixed
+
+- Desktop background to be applied to either file or folder depending if slideshow is enabled ([#7138](https://github.com/linuxmint/cinnamon-spices-applets/issues/7138)).
+- Background's file/folder to support non-ASCII URIs.
+
+## [1.2.2] - 2025-01-23 - [#6797](https://github.com/linuxmint/cinnamon-spices-applets/pull/6797)
+
+### Fixed
+
+- Missing import in time change listener's `main.cpp` for `g++` 14.2 ([#6791](https://github.com/linuxmint/cinnamon-spices-applets/issues/6791)).
+
+## [1.2.1] - 2024-10-22 - [#6524](https://github.com/linuxmint/cinnamon-spices-applets/pull/6524)
+
+### Added
+
+- Shell features support for custom commands launching.
+
+### Changed
+
+- Custom commands launching's list's `Active` attribute to default to `true`.
+
+## [1.2.0] - 2024-10-22 - [#6521](https://github.com/linuxmint/cinnamon-spices-applets/pull/6521)
+
+### Added
+
+- Custom commands launching.
+
+## [1.1.0] - 2024-09-02 - [#6361](https://github.com/linuxmint/cinnamon-spices-applets/pull/6361)
+
+### Added
+
+- Desktop background support ([#6354](https://github.com/linuxmint/cinnamon-spices-applets/issues/6354)).
+
+## [1.0.1] - 2024-08-26 - [#6344](https://github.com/linuxmint/cinnamon-spices-applets/pull/6344)
+
+### Fixed
+
+- `GLib.DateTime` used methods to be compatible with `GLib` < 2.80 ([#6341](https://github.com/linuxmint/cinnamon-spices-applets/issues/6341)).
+
+## [1.0.0] - 2025-08-26 - [#6329](https://github.com/linuxmint/cinnamon-spices-applets/pull/6329)
+
+### Added
 
 - Initial release
diff --git a/auto-dark-light@gihaume/CONTRIBUTING.md b/auto-dark-light@gihaume/CONTRIBUTING.md
@@ -0,0 +1,144 @@
+# Contributing
+
+## Dependencies
+
+### Global
+
+- [pnpm](https://pnpm.io/installation#on-posix-systems) (tested v10.24.0).
+
+### Local
+
+- Install dependencies:
+  ```bash
+  pnpm i  # shortcut for `pnpm install`
+  ```
+  - It needs to be done after each `git pull` that changes `pnpm-lock.yaml`.
+  - It creates a `node_modules` folder with symlinks to a global store, so:
+    - The global store can be pruned after the local `node_modules` folder has been deleted:
+      ```bash
+      pnpm store prune
+      ```
+    - Or to have the files installed in this folder instead of the global store, use exclusively:
+      ```bash
+      pnpm i --store-dir=.pnpm-store
+      ```
+
+### Optional
+
+- [Visual Studio Code](https://code.visualstudio.com)
+  - With the extensions in [`.vscode/extensions.json`](./.vscode/extensions.json).
+- `poedit` for translation:
+  - On Debian-based systems:
+    ```bash
+    sudo apt install poedit
+    ```
+
+## Conventions
+### Files organization
+
+- `doc`: applet development documentation
+- `src`: source files
+  - `app`: application specifics
+    - `core`: business logic
+    - `ui`: user interface bindings
+  - `lib`: reusable generic library
+    - `core`: business logic
+    - `sys`: system/OS interfacing
+      - `cinnamon`: Cinnamon desktop environment specifics
+      - `gnome`: GNOME desktop environment specifics
+
+Notes :
+- Nothing in `lib` depends on anything in `app`.
+- Some files in `sys` are not in TypeScript so they are more reusable and directly launchable by GnomeJS in order to test them.
+
+### Style
+
+- See [`.editorconfig`](./.editorconfig).
+- Variables names uses `snake_case`.
+- Classes names uses `Capitalized_snake_case`.
+- Where both single and double quotes are possible:
+  - single quotes means to reference to something existing,
+  - double quotes means to create something new.
+- Braces placement: [K&R](https://en.wikipedia.org/wiki/Indentation_style#K&R) but also for functions.
+- Brackets the same as braces as soon as their content is too big for one line.
+- When a list content or function arguments is too big for one line:
+  - A new line under can have all arguments if they fit in one line,
+  - As soon as they don't fit in one line: one argument per line.
+- All instructions are terminated by semicolons: ASI is considered a fallback and not a feature.
+
+## Development workflow
+
+- Create a symbolic link pointing to this folder and add it in your user applets folder:
+  ```bash
+  ln -s \
+      <path_to_this_folder>/files/auto-dark-light@gihaume \
+      ~/.local/share/cinnamon/applets/auto-dark-light@gihaume
+  ```
+  - Alternatively, it can be created via GUI with the handy Cinnamon Spices' Action [`create-desktop-shortcut@anaximeno`](https://cinnamon-spices.linuxmint.com/actions/view/11).
+- Launch the continuous and incremental build of `applet.js` triggered on each source file save:
+  ```bash
+  pnpm dev
+  ```
+  - Modify source files in `src/` as wanted.
+  - Reset Cinnamon with `Ctrl`+`Alt`+`Esc` for loading and testing the applet's new version.
+    - Debug with:
+      - Looking Glass logs (`Alt`+`F2`, type `lg`, `Enter`),
+      - `~/.xsession-errors` logs file.
+  - Press `Ctrl`+`C` (`SIGINT`) to stop the continuous build.
+
+## Unit testing
+
+### Core logic
+
+- Run all core logic automatic unit tests:
+  ```bash
+  pnpm test
+  ```
+  - The VS Code extension [Vitest](vscode:extension/vitest.explorer) can also be used.
+
+### System/OS interfacing
+
+Check `test *.js` files in various `tests` folders and run them manually according to their instructions in their headers.
+
+## Committing
+
+Before any commit:
+
+- All core logic automatic unit tests must pass.
+- If any system/OS interfacing has been modified, related manual tests must be performed again carefully.
+- It is advisable to build `applet.js` in a single run with:
+  ```bash
+  pnpm build
+  ```
+  - then E2E test again.
+- The change has to be documented as an incremented version in `CHANGELOG.md` accordingly.
+  - The version number has to be modified in `files/metadata.json` accordingly.
+- If some call to gettext `_("…")` has been added or modified, the following command must be run from the root of the cinnamon spices repository to update the `.pot` translation template file:
+  ```bash
+  ./cinnamon-spices-makepot auto-dark-light@gihaume
+  ```
+
+## Documentation
+
+Check [`doc/README.md`](./doc/README.md).
+
+## Linting for Python widgets (experimental)
+
+### Installation
+
+- Create environment:
+  ```sh
+  python -m venv .venv --system-site-packages
+  ```
+- Install dependencies:
+  ```sh
+  ./.venv/bin/pip install -r requirements.txt
+  ```
+
+### Setting up in VS Code
+
+- Install the `ms-python.python` extension.
+- Select the Python interpreter from the `.venv` folder:
+  - Launch the Command Palette with `Ctrl`+`Shift`+`P`
+  - Select `Python: Select Interpreter`
+  - Select the one from the `.venv` folder.
diff --git a/auto-dark-light@gihaume/CREDITS.md b/auto-dark-light@gihaume/CREDITS.md
@@ -0,0 +1,4 @@
+# Credits
+
+- [SunCalc](https://github.com/mourner/suncalc): twilights calculations from geographical coordinates and date
+- [MobX](https://mobx.js.org): reactive state management
diff --git a/auto-dark-light@gihaume/README.md b/auto-dark-light@gihaume/README.md
@@ -1,47 +1,48 @@
 # Automatic dark/light themes
 
-This Cinnamon applet brings the ability to automatically switch between dark and light themes and desktop background at twilight times based on a location.
+This Cinnamon applet brings the ability to automatically switch between dark and light appearances at twilights times based on a location or some user set schedules.
+
+The appearance consists of:
+- themes,
+- desktop background,
+- shell commands to be launched when switching.
 
 ## Features
 
-- Dump system themes and desktop background settings as light/dark presets in one click in order to keep using the Cinnamon settings menu.
+- Save system themes and desktop background settings as light/dark presets in one click.
 - Sync location from the system `Region` and `City` settings using a local database to automatically determine the geographical coordinates.
-- Enter manually any geographical coordinates if needed.
-- Always sync instantaneously with external changes of color scheme, region/city and time (useful in e.g. after a sleep wake up).
-- Fully event and scheduling based, zero polling.
-- Automatic mode switch can be disabled.
-- Dark/light mode can always be switched manually.
-- Schedule any amount of commands to launch at twilight times.
+  - Or enter manually any geographical coordinates if needed.
+- Compute twilights times from geographical coordinates and add them some offset or just set them arbitrarily.
+- Always sync instantaneously with system changes of color scheme (appearance), region/city and time (useful in e.g. after a sleep wake up).
+- Automatic appearance switch can be disabled.
+- Dark/light appearance can always be switched manually.
+- Almost everything is fully event-listening and scheduling based (no active monitoring, except for wall-clock adjustment).
 
 ## Applet icons legend
 
 <div style="display: flex; align-items: center; margin-top: 20px; margin-bottom: 20px;">
     <img src="https://raw.githubusercontent.com/linuxmint/cinnamon-spices-applets/master/auto-dark-light@gihaume/files/auto-dark-light@gihaume/5.8/icons/auto-symbolic.svg" alt="Auto" width="75" height="75" style="margin-right: 20px;">
-    Automatic mode switch enabled.
+    Automatic appearance switch enabled.
 </div>
 <div style="display: flex; align-items: center; margin-top: 20px; margin-bottom: 20px;">
     <img src="https://raw.githubusercontent.com/linuxmint/cinnamon-spices-applets/master/auto-dark-light@gihaume/files/auto-dark-light@gihaume/5.8/icons/auto-inverted-symbolic.svg" alt="Auto inverted" width="75" height="75" style="margin-right: 20px;">
-    Automatic mode switch enabled but the current mode has been set while not in sync with the actual daytime, so any external changes won't update it until the next scheduled mode change or if entering auto mode switch again.
+    Automatic appearance switch enabled but the current appearance has been set while not in sync with the actual daytime, so any external changes won't update it until the next scheduled appearance change or if entering in automatic appearance switch mode again.
 </div>
 <div style="display: flex; align-items: center; margin-top: 20px; margin-bottom: 20px;">
     <img src="https://raw.githubusercontent.com/linuxmint/cinnamon-spices-applets/master/auto-dark-light@gihaume/files/auto-dark-light@gihaume/5.8/icons/light-symbolic.svg" alt="Light" width="75" height="75" style="margin-right: 20px;">
-    Automatic mode switch disabled and the current mode is light.
+    Automatic appearance switch disabled and the current appearance is light.
 </div>
 <div style="display: flex; align-items: center; margin-top: 20px; margin-bottom: 20px;">
     <img src="https://raw.githubusercontent.com/linuxmint/cinnamon-spices-applets/master/auto-dark-light@gihaume/files/auto-dark-light@gihaume/5.8/icons/dark-symbolic.svg" alt="Dark" width="75" height="75" style="margin-right: 20px;">
-    Automatic mode switch disabled and the current mode is dark.
+    Automatic appearance switch disabled and the current appearance is dark.
+</div>
+<div style="display: flex; align-items: center; margin-top: 20px; margin-bottom: 20px;">
+    <img src="https://raw.githubusercontent.com/linuxmint/cinnamon-spices-applets/master/auto-dark-light@gihaume/files/auto-dark-light@gihaume/5.8/icons/on-error-symbolic.svg" alt="Error" width="75" height="75" style="margin-right: 20px;">
+    The applet is in an error state and is not functional. A notification should have been shown giving more details about the error. If it has disappeared, it is possible to find it in the Looking Glass logs: press Alt+F2 and enter 'lg'.
 </div>
-
-## Dependencies
-
-`make` and `g++`, which can be installed on Debian-based system with `sudo apt install make g++`.
 
 ## Feedback
 
-Add a `⭐ Score` on the [Cinnamon spices](https://cinnamon-spices.linuxmint.com/applets/view/397) page if you like this applet.
-
-Report issues on the [GitHub repository](https://github.com/linuxmint/cinnamon-spices-applets/issues) in mentioning `@guillaume-mueller`.
-
-## Donate
-
-[Buy me a coffee](https://buymeacoffee.com/gihaume)
+- Add a `⭐ Score` on the [Cinnamon spices page](https://cinnamon-spices.linuxmint.com/applets/view/397)'s top if you like this applet.
+- Report issues or request features on the [GitHub repository](https://github.com/linuxmint/cinnamon-spices-applets/issues?q=is:issue+is:open+auto-dark-light@gihaume).
+- [Buy me a coffee](https://buymeacoffee.com/gihaume) if you'd like.