add Dark Mode API to detect user preference and listen for theme changes

Author: dev-aditya-lab

README.md

@@ -590,6 +590,89 @@ startIdleTimer(10, () => {
 * Lock app after idle timeout in sensitive dashboards
 ---
 
+# 🌙 Dark Mode API – webdev-power-kit
+
+This module detects whether the user prefers dark or light mode, and lets you listen to theme changes in real-time using the system’s color scheme preference.
+
+---
+
+## ✨ Features
+
+* Detect if dark mode is enabled by system/browser
+* Listen for real-time theme changes
+* Useful for automatic theming or toggles
+* Uses native `window.matchMedia`
+
+---
+
+## ✅ Functions
+
+### 1. `isDarkMode()`
+
+📌 Returns whether the user’s system prefers dark mode.
+
+```js
+import { isDarkMode } from "webdev-power-kit";
+
+if (isDarkMode()) {
+  console.log("🌙 Dark mode is enabled");
+} else {
+  console.log("☀️ Light mode is enabled");
+}
+```
+
+#### 🔁 Returns:
+
+* `true` → if user prefers dark mode
+* `false` → if light mode is preferred
+
+---
+
+### 2. `listenDarkMode(callback)`
+
+📌 Listen to changes in the system theme (dark ↔️ light) in real-time.
+
+```js
+import { listenDarkMode } from "webdev-power-kit";
+
+listenDarkMode((isDark) => {
+  console.log("Theme changed:", isDark ? "Dark" : "Light");
+});
+```
+
+#### 📥 Parameters:
+
+| Param      | Type                        | Description                                              |
+| ---------- | --------------------------- | -------------------------------------------------------- |
+| `callback` | `(isDark: boolean) => void` | Called with `true` for dark mode, `false` for light mode |
+
+#### 🔁 Returns:
+
+* A function to unsubscribe and stop listening
+
+---
+
+## 🔐 Browser Support
+
+| Browser | Supported? | Notes                            |
+| ------- | ---------- | -------------------------------- |
+| Chrome  | ✅          | Fully supported                  |
+| Firefox | ✅          | Fully supported                  |
+| Edge    | ✅          | Fully supported                  |
+| Safari  | ✅          | Fully supported (macOS/iOS only) |
+| Mobile  | ✅          | Most modern devices supported    |
+
+---
+
+## 💡 Use Cases
+
+* Auto-switch theme on page load
+* Show theme toggle suggestion
+* Sync app theme with OS settings
+* Apply different CSS styles dynamically
+
+---
+
 
 
 

cnddocs.md

@@ -0,0 +1,82 @@
+
+# 🌙 Dark Mode API – webdev-power-kit
+
+This module detects whether the user prefers dark or light mode, and lets you listen to theme changes in real-time using the system’s color scheme preference.
+
+---
+
+## ✨ Features
+
+* Detect if dark mode is enabled by system/browser
+* Listen for real-time theme changes
+* Useful for automatic theming or toggles
+* Uses native `window.matchMedia`
+
+---
+
+## ✅ Functions
+
+### 1. `isDarkMode()`
+
+📌 Returns whether the user’s system prefers dark mode.
+
+```js
+import { isDarkMode } from "webdev-power-kit";
+
+if (isDarkMode()) {
+  console.log("🌙 Dark mode is enabled");
+} else {
+  console.log("☀️ Light mode is enabled");
+}
+```
+
+#### 🔁 Returns:
+
+* `true` → if user prefers dark mode
+* `false` → if light mode is preferred
+
+---
+
+### 2. `listenDarkMode(callback)`
+
+📌 Listen to changes in the system theme (dark ↔️ light) in real-time.
+
+```js
+import { listenDarkMode } from "webdev-power-kit";
+
+listenDarkMode((isDark) => {
+  console.log("Theme changed:", isDark ? "Dark" : "Light");
+});
+```
+
+#### 📥 Parameters:
+
+| Param      | Type                        | Description                                              |
+| ---------- | --------------------------- | -------------------------------------------------------- |
+| `callback` | `(isDark: boolean) => void` | Called with `true` for dark mode, `false` for light mode |
+
+#### 🔁 Returns:
+
+* A function to unsubscribe and stop listening
+
+---
+
+## 🔐 Browser Support
+
+| Browser | Supported? | Notes                            |
+| ------- | ---------- | -------------------------------- |
+| Chrome  | ✅          | Fully supported                  |
+| Firefox | ✅          | Fully supported                  |
+| Edge    | ✅          | Fully supported                  |
+| Safari  | ✅          | Fully supported (macOS/iOS only) |
+| Mobile  | ✅          | Most modern devices supported    |
+
+---
+
+## 💡 Use Cases
+
+* Auto-switch theme on page load
+* Show theme toggle suggestion
+* Sync app theme with OS settings
+* Apply different CSS styles dynamically
+

src/darkMode.js

@@ -0,0 +1,27 @@
+/**
+ * Detect if user prefers dark mode based on system/browser settings.
+ * @returns {boolean} - true if dark mode is preferred
+ */
+export function isDarkMode() {
+  return window.matchMedia &&
+    window.matchMedia("(prefers-color-scheme: dark)").matches;
+}
+
+/**
+ * Listen for system theme changes in real-time.
+ * @param {(isDark: boolean) => void} callback - Called when theme changes
+ * @returns {() => void} - Function to remove listener
+ */
+export function listenDarkMode(callback) {
+  const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
+  const handler = (e) => callback(e.matches);
+
+  mediaQuery.addEventListener("change", handler);
+
+  // Trigger once initially
+  callback(mediaQuery.matches);
+
+  return () => {
+    mediaQuery.removeEventListener("change", handler);
+  };
+}

src/index.js

@@ -6,3 +6,4 @@ export * from './network.js';
 export * from './tabVisibility.js';
 export * from './preventClose.js';
 export * from './idleTimer.js';
+export * from './darkMode.js';

test/index.html

@@ -23,7 +23,8 @@ <h2>Clipboard Test</h2>
   <hr>
   <button id="enable">Enable Tab Protection</button>
 <button id="disable">Disable Tab Protection</button>
-
+<hr>
+<p id="theme-status">Checking theme...</p>
   <script type="module" src="testScript.js"> </script>
 </body>
 </html>

test/testScript.js

@@ -5,7 +5,12 @@ import { isOnline, listenNetworkStatus } from "../src/index.js";
 import { listenTabVisibility } from "../src/index.js";
 import { preventTabClose } from "../src/index.js";
 import { startIdleTimer } from "../src/index.js";
+import { isDarkMode, listenDarkMode } from "../src/index.js";
 
+listenDarkMode((isDark) => {
+  document.getElementById("theme-status").textContent =
+    isDark ? "🌙 Dark mode enabled" : "☀️ Light mode enabled";
+});
 startIdleTimer(5, () => {
   document.getElementById("idle").textContent = "💤 You are idle!";
 });