use-green-mode 1.0.0

package/README.md

@@ -0,0 +1,74 @@
+# 🌿 use-green-mode
+
+A lightweight, eco-friendly React hook that gracefully degrades your UI to save battery and data. 
+
+Modern web apps are heavy. When a user's device is dying or their connection drops, running 60fps animations and loading 4K images drains their battery faster. `use-green-mode` watches native browser APIs and gives you a simple set of boolean flags to turn off the heavy stuff when your users need it most.
+
+## ✨ Features
+* **Zero React Context:** Powered by an independent Vanilla JS engine (Nano Stores).
+* **Event-Driven:** Listens to the Battery Status API instead of expensive polling.
+* **Network Aware:** Detects `Save-Data` headers and 2G/3G connections.
+* **CPU Aware:** Checks `hardwareConcurrency` for low-end devices.
+* **Tiny & Fast:** Built with `tsup` for maximum tree-shaking.
+
+## 📦 Installation
+
+```bash
+npm install use-green-mode
+# or
+yarn add use-green-mode
+```
+# 🚀 Quick Start
+
+Drop `useGreenMode` into your top-level component. It automatically calculates an `energyScore` (0 to 100) and toggles features based on safe defaults.
+
+```
+import { useGreenMode } from 'use-green-mode';
+import { motion } from 'framer-motion';
+
+export function App() {
+  const { lowRes, stopAnimations, ecoTheme } = useGreenMode();
+
+  return (
+    <div className={ecoTheme ? 'theme-dark-high-contrast' : 'theme-standard'}>
+      {/* 1. Serve smaller images when data/battery is low */}
+      <img 
+        src={lowRes ? '/hero-tiny.jpg' : '/hero-4k.jpg'} 
+        alt="Hero Background" 
+      />
+
+      {/* 2. Kill heavy animations to save CPU/Battery */}
+      {!stopAnimations && (
+        <motion.div animate={{ rotate: 360 }} />
+      )}
+    </div>
+  );
+}
+```
+# ⚙️ Customization
+
+You can pass custom thresholds to define exactly when your app goes into "survival mode."
+
+```
+const { stopAnimations, ecoTheme } = useGreenMode({
+  lowResAt: 80,         // Trigger earlier
+  stopAnimationsAt: 50, // Default
+  ecoThemeAt: 15        // Only on extreme low battery
+});
+```
+
+# 🛠️ Vanilla JS Usage
+
+Not using React? You can use the core engine directly anywhere in your JavaScript.
+
+```
+import { energyScore, initGreenObserver } from 'use-green-mode/engine';
+
+initGreenObserver();
+
+energyScore.subscribe((score) => {
+  if (score < 50) {
+    document.body.classList.add('stop-animations');
+  }
+});
+```

package/dist/index.d.mts

@@ -0,0 +1,18 @@
+import * as nanostores from 'nanostores';
+
+interface GreenThresholds {
+    lowResAt?: number;
+    stopAnimationsAt?: number;
+    ecoThemeAt?: number;
+}
+declare function useGreenMode(thresholds?: GreenThresholds): {
+    score: number;
+    lowRes: boolean;
+    stopAnimations: boolean;
+    ecoTheme: boolean;
+};
+
+declare const energyScore: nanostores.PreinitializedWritableAtom<number> & object;
+declare function initGreenObserver(): void;
+
+export { energyScore, initGreenObserver, useGreenMode };

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+import * as nanostores from 'nanostores';
+
+interface GreenThresholds {
+    lowResAt?: number;
+    stopAnimationsAt?: number;
+    ecoThemeAt?: number;
+}
+declare function useGreenMode(thresholds?: GreenThresholds): {
+    score: number;
+    lowRes: boolean;
+    stopAnimations: boolean;
+    ecoTheme: boolean;
+};
+
+declare const energyScore: nanostores.PreinitializedWritableAtom<number> & object;
+declare function initGreenObserver(): void;
+
+export { energyScore, initGreenObserver, useGreenMode };

package/dist/index.js

@@ -0,0 +1,87 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  energyScore: () => energyScore,
+  initGreenObserver: () => initGreenObserver,
+  useGreenMode: () => useGreenMode
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/useGreenMode.ts
+var import_react = require("react");
+var import_react2 = require("@nanostores/react");
+
+// src/engine.ts
+var import_nanostores = require("nanostores");
+var energyScore = (0, import_nanostores.atom)(100);
+var isBrowser = typeof window !== "undefined" && typeof navigator !== "undefined";
+function initGreenObserver() {
+  if (!isBrowser) return;
+  const calculateScore = () => {
+    let score = 100;
+    if (navigator.hardwareConcurrency && navigator.hardwareConcurrency <= 4) score -= 20;
+    const connection = navigator.connection;
+    if (connection) {
+      if (connection.saveData) score -= 40;
+      if (["slow-2g", "2g", "3g"].includes(connection.effectiveType)) score -= 30;
+    }
+    energyScore.set(Math.max(0, score));
+  };
+  if ("getBattery" in navigator) {
+    navigator.getBattery().then((battery) => {
+      const updateBatteryImpact = () => {
+        let currentScore = energyScore.get();
+        if (!battery.charging && battery.level <= 0.2) {
+          energyScore.set(Math.max(0, currentScore - 50));
+        } else {
+          calculateScore();
+        }
+      };
+      updateBatteryImpact();
+      battery.addEventListener("levelchange", updateBatteryImpact);
+      battery.addEventListener("chargingchange", updateBatteryImpact);
+    });
+  } else {
+    calculateScore();
+  }
+}
+
+// src/useGreenMode.ts
+function useGreenMode(thresholds = {}) {
+  const { lowResAt = 70, stopAnimationsAt = 50, ecoThemeAt = 30 } = thresholds;
+  const score = (0, import_react2.useStore)(energyScore);
+  (0, import_react.useEffect)(() => {
+    initGreenObserver();
+  }, []);
+  return {
+    score,
+    lowRes: score <= lowResAt,
+    stopAnimations: score <= stopAnimationsAt,
+    ecoTheme: score <= ecoThemeAt
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  energyScore,
+  initGreenObserver,
+  useGreenMode
+});

package/dist/index.mjs

@@ -0,0 +1,58 @@
+// src/useGreenMode.ts
+import { useEffect } from "react";
+import { useStore } from "@nanostores/react";
+
+// src/engine.ts
+import { atom } from "nanostores";
+var energyScore = atom(100);
+var isBrowser = typeof window !== "undefined" && typeof navigator !== "undefined";
+function initGreenObserver() {
+  if (!isBrowser) return;
+  const calculateScore = () => {
+    let score = 100;
+    if (navigator.hardwareConcurrency && navigator.hardwareConcurrency <= 4) score -= 20;
+    const connection = navigator.connection;
+    if (connection) {
+      if (connection.saveData) score -= 40;
+      if (["slow-2g", "2g", "3g"].includes(connection.effectiveType)) score -= 30;
+    }
+    energyScore.set(Math.max(0, score));
+  };
+  if ("getBattery" in navigator) {
+    navigator.getBattery().then((battery) => {
+      const updateBatteryImpact = () => {
+        let currentScore = energyScore.get();
+        if (!battery.charging && battery.level <= 0.2) {
+          energyScore.set(Math.max(0, currentScore - 50));
+        } else {
+          calculateScore();
+        }
+      };
+      updateBatteryImpact();
+      battery.addEventListener("levelchange", updateBatteryImpact);
+      battery.addEventListener("chargingchange", updateBatteryImpact);
+    });
+  } else {
+    calculateScore();
+  }
+}
+
+// src/useGreenMode.ts
+function useGreenMode(thresholds = {}) {
+  const { lowResAt = 70, stopAnimationsAt = 50, ecoThemeAt = 30 } = thresholds;
+  const score = useStore(energyScore);
+  useEffect(() => {
+    initGreenObserver();
+  }, []);
+  return {
+    score,
+    lowRes: score <= lowResAt,
+    stopAnimations: score <= stopAnimationsAt,
+    ecoTheme: score <= ecoThemeAt
+  };
+}
+export {
+  energyScore,
+  initGreenObserver,
+  useGreenMode
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "use-green-mode",
+  "version": "1.0.0",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "UdhayaKumar",
+  "license": "MIT",
+  "type": "commonjs",
+  "description": "",
+  "dependencies": {
+    "@nanostores/react": "^1.0.0",
+    "nanostores": "^1.1.1"
+  },
+  "peerDependencies": {
+    "react": "^19.2.4"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  }
+}

package/src/engine.ts

@@ -0,0 +1,42 @@
+import { atom } from 'nanostores';
+
+export const energyScore = atom<number>(100);
+
+const isBrowser = typeof window !== 'undefined' && typeof navigator !== 'undefined';
+
+export function initGreenObserver() {
+  if (!isBrowser) return;
+
+  const calculateScore = () => {
+    let score = 100;
+    
+    if (navigator.hardwareConcurrency && navigator.hardwareConcurrency <= 4) score -= 20;
+
+    const connection = (navigator as any).connection;
+    if (connection) {
+      if (connection.saveData) score -= 40;
+      if (['slow-2g', '2g', '3g'].includes(connection.effectiveType)) score -= 30;
+    }
+
+    energyScore.set(Math.max(0, score));
+  };
+
+  if ('getBattery' in navigator) {
+    (navigator as any).getBattery().then((battery: any) => {
+      const updateBatteryImpact = () => {
+        let currentScore = energyScore.get();
+        if (!battery.charging && battery.level <= 0.2) {
+          energyScore.set(Math.max(0, currentScore - 50));
+        } else {
+          calculateScore();
+        }
+      };
+
+      updateBatteryImpact();
+      battery.addEventListener('levelchange', updateBatteryImpact);
+      battery.addEventListener('chargingchange', updateBatteryImpact);
+    });
+  } else {
+    calculateScore();
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { useGreenMode } from './useGreenMode';
+export { energyScore, initGreenObserver } from './engine';

package/src/useGreenMode.ts

@@ -0,0 +1,25 @@
+import { useEffect } from 'react';
+import { useStore } from '@nanostores/react';
+import { energyScore, initGreenObserver } from './engine';
+
+interface GreenThresholds {
+  lowResAt?: number;
+  stopAnimationsAt?: number;
+  ecoThemeAt?: number;
+}
+
+export function useGreenMode(thresholds: GreenThresholds = {}) {
+  const { lowResAt = 70, stopAnimationsAt = 50, ecoThemeAt = 30 } = thresholds;
+  const score = useStore(energyScore);
+
+  useEffect(() => {
+    initGreenObserver();
+  }, []);
+
+  return {
+    score,
+    lowRes: score <= lowResAt,
+    stopAnimations: score <= stopAnimationsAt,
+    ecoTheme: score <= ecoThemeAt,
+  };
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "jsx": "react",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "node"
+  },
+  "include": ["src"]
+}