@c-technology/adaptive-ui 0.1.0

package/README.md

@@ -0,0 +1,332 @@
+# adaptive-ui
+
+> **Human-aware UI adaptation for modern web apps**
+
+adaptive-ui is a **TypeScript-first library** that helps your UI adapt to **users**, not just screen sizes.
+
+Instead of only responding to `mobile`, `desktop`, or `tablet`, adaptive-ui reacts to **real conditions** like:
+
+* slow network
+* low battery
+* user impatience
+* first-time vs returning users
+* accessibility stress
+
+This README explains everything **from zero**, assuming you are a beginner.
+
+---
+
+## 🚨 The Problem (Why adaptive-ui Exists)
+
+Most web apps today:
+
+* look responsive
+* but feel frustrating
+
+Why?
+Because they adapt to **screens**, not **people**.
+
+Examples:
+
+* User has slow internet → app still loads heavy animations
+* User is confused → UI gives no guidance
+* User is impatient → UI hides important actions
+* User has low battery → app keeps wasting power
+
+Developers usually fix this by writing **random `if` statements everywhere**.
+
+That approach:
+
+* does not scale
+* is hard to reason about
+* creates messy code
+
+**adaptive-ui solves this by acting as a decision layer for your UI.**
+
+---
+
+## 🧠 What adaptive-ui Is (And Is NOT)
+
+### ✅ What it IS
+
+* a **logic layer** for UI behavior
+* a way to detect user context
+* a strategy system for adapting interfaces
+* framework-friendly (React, Next.js, etc.)
+
+### ❌ What it is NOT
+
+* ❌ a UI component library
+* ❌ a design system
+* ❌ an analytics tool
+* ❌ an AI / ML system
+* ❌ a tracking library
+
+adaptive-ui **never renders UI**. It only helps you make better decisions.
+
+---
+
+## 🏗️ How adaptive-ui Works (Simple Explanation)
+
+adaptive-ui works in **three steps**:
+
+### 1️⃣ Detect Signals
+
+Signals are things like:
+
+* slow network
+* low battery
+* many rapid clicks (impatience)
+
+### 2️⃣ Build Context
+
+From signals, adaptive-ui builds a **context**, such as:
+
+* `slow-network`
+* `impatient`
+* `new-user`
+
+### 3️⃣ Run Strategies
+
+Strategies say:
+
+> "When these conditions are true → do this"
+
+Example:
+
+* If user is impatient → simplify the UI
+* If network is slow → disable animations
+
+---
+
+## 📦 Installation
+
+```bash
+npm install adaptive-ui
+```
+
+or
+
+```bash
+pnpm install adaptive-ui
+```
+
+or
+
+```bash
+bun add adaptive-ui
+```
+
+or
+
+```bash
+yarn add adaptive-ui
+```
+
+---
+
+## ⚛️ Basic Usage (React / Next.js)
+
+### Step 1: Import the hook
+
+```ts
+import { useAdaptive } from "adaptive-ui";
+```
+
+---
+
+### Step 2: Use it inside a component
+
+```tsx
+export default function Dashboard() {
+  const ui = useAdaptive();
+
+  return <h1>Dashboard</h1>;
+}
+```
+
+This gives you access to the **adaptive engine**.
+
+---
+
+## 🧩 Context Detection (Beginner Friendly)
+
+adaptive-ui automatically detects some conditions.
+
+### Example: Check if user is impatient
+
+```tsx
+if (ui.has("impatient")) {
+  console.log("User is impatient");
+}
+```
+
+You don’t need to know *how* impatience is detected.
+
+That logic is handled internally.
+
+---
+
+## 🧠 Strategies (The Core Feature)
+
+Strategies define **how your UI should react**.
+
+### Example: Lite UI on slow network
+
+```ts
+ui.strategy({
+  conditions: ["slow-network"],
+  actions: () => {
+    document.body.classList.add("ui-lite");
+  }
+});
+```
+
+This means:
+
+> If network is slow → switch to lite UI
+
+---
+
+### Example: Focus mode for impatient users
+
+```ts
+ui.strategy({
+  conditions: ["impatient"],
+  actions: () => {
+    document.body.classList.add("ui-focus");
+  }
+});
+```
+
+---
+
+### Run strategies
+
+```ts
+ui.run();
+```
+
+This applies all matching strategies.
+
+---
+
+## 🎨 Example CSS
+
+```css
+.ui-lite * {
+  animation: none !important;
+  transition: none !important;
+}
+
+.ui-focus nav,
+.ui-focus aside {
+  display: none;
+}
+```
+
+Your UI now adapts **without changing components**.
+
+---
+
+## 🧪 Debugging (Very Important)
+
+To understand *why* the UI changed:
+
+```ts
+console.log(ui.explain());
+```
+
+Output:
+
+```ts
+{
+  context: ["slow-network", "impatient"],
+  strategies: 2
+}
+```
+
+This helps avoid confusion during development.
+
+---
+
+## ♿ Accessibility-Friendly by Design
+
+adaptive-ui helps you:
+
+* reduce motion
+* simplify layouts
+* increase clarity
+
+Without extra libraries.
+
+It reacts to **behavior**, not user labels.
+
+---
+
+## 🚀 Why Use adaptive-ui?
+
+* cleaner UI logic
+* fewer edge cases
+* better UX automatically
+* no heavy setup
+* beginner-friendly
+
+Once added, it quietly improves your app.
+
+---
+
+## 🧱 What adaptive-ui Will NEVER Do
+
+To keep trust high:
+
+* ❌ no analytics
+* ❌ no tracking
+* ❌ no AI
+* ❌ no user profiling
+* ❌ no remote configs
+
+Your app stays **privacy-respecting**.
+
+---
+
+## 🛣️ Roadmap
+
+Planned features:
+
+* debug overlay
+* persistent context
+* strategy priorities
+* plugin system
+
+Not planned:
+
+* ML models
+* server-side tracking
+* UI rendering
+
+---
+
+## 🧠 Philosophy
+
+> Good UI should feel invisible.
+
+adaptive-ui helps you build interfaces that **respect users**, without extra complexity.
+
+---
+
+## 📄 License
+
+MIT License
+
+---
+
+## 🙌 Final Note
+
+If you are a beginner:
+
+* start small
+* add one strategy
+* observe the effect
+
+adaptive-ui grows **with your understanding**, not against it.

package/dist/index.cjs

@@ -0,0 +1,116 @@
+"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, {
+  AdaptiveUI: () => AdaptiveUI,
+  focusMode: () => focusMode,
+  liteUI: () => liteUI,
+  useAdaptive: () => useAdaptive
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/adaptive.ts
+var AdaptiveUI = class {
+  constructor() {
+    this.context = /* @__PURE__ */ new Set();
+    this.strategies = [];
+  }
+  addContext(ctx) {
+    this.context.add(ctx);
+  }
+  has(ctx) {
+    return this.context.has(ctx);
+  }
+  strategy(strategy) {
+    this.strategies.push(strategy);
+  }
+  run() {
+    for (const s of this.strategies) {
+      if (s.conditions.every((c) => this.context.has(c))) {
+        s.actions();
+      }
+    }
+  }
+  explain() {
+    return {
+      context: Array.from(this.context),
+      strategies: this.strategies.length
+    };
+  }
+};
+
+// src/react.ts
+var import_react = require("react");
+
+// src/signals/network.ts
+function detectSlowNetwork(onDetect) {
+  const connection = navigator.connection;
+  if (!connection) return;
+  if (connection.effectiveType === "2g" || connection.effectiveType === "slow-2g") {
+    onDetect();
+  }
+}
+
+// src/signals/battery.ts
+async function detectLowBattery(onDetect) {
+  if (!("getBattery" in navigator)) return;
+  const battery = await navigator.getBattery();
+  if (battery.level < 0.2) {
+    onDetect();
+  }
+}
+
+// src/signals/behavior.ts
+function detectImpatience(onDetect) {
+  let clicks = 0;
+  window.addEventListener("click", () => {
+    clicks++;
+    if (clicks >= 6) {
+      onDetect();
+    }
+  });
+}
+
+// src/react.ts
+function useAdaptive() {
+  const [adaptive] = (0, import_react.useState)(() => new AdaptiveUI());
+  (0, import_react.useEffect)(() => {
+    detectSlowNetwork(() => adaptive.addContext("slow-network"));
+    detectLowBattery(() => adaptive.addContext("low-battery"));
+    detectImpatience(() => adaptive.addContext("impatient"));
+  }, []);
+  return adaptive;
+}
+
+// src/strategies.ts
+function liteUI() {
+  document.body.classList.add("ui-lite");
+}
+function focusMode() {
+  document.body.classList.add("ui-focus");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AdaptiveUI,
+  focusMode,
+  liteUI,
+  useAdaptive
+});

package/dist/index.d.cts

@@ -0,0 +1,24 @@
+type Context = "slow-network" | "low-battery" | "impatient" | "new-user";
+type Strategy = {
+    conditions: Context[];
+    actions: () => void;
+};
+declare class AdaptiveUI {
+    private context;
+    private strategies;
+    addContext(ctx: Context): void;
+    has(ctx: Context): boolean;
+    strategy(strategy: Strategy): void;
+    run(): void;
+    explain(): {
+        context: Context[];
+        strategies: number;
+    };
+}
+
+declare function useAdaptive(): AdaptiveUI;
+
+declare function liteUI(): void;
+declare function focusMode(): void;
+
+export { AdaptiveUI, focusMode, liteUI, useAdaptive };

package/package.json

@@ -0,0 +1,45 @@
+{
+"name": "@c-technology/adaptive-ui",
+  "version": "0.1.0",
+  "description": "Human-aware UI adaptation layer for web apps",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+"files": [
+    "dist"
+],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup src/index.ts --dts",
+    "dev": "tsup --watch",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.7",
+    "react": "^19.2.3",
+    "tsup": "^8.5.1",
+    "typescript": "^5.3.0"
+  },
+  "keywords": [
+    "adaptive-ui",
+    "ux",
+    "accessibility",
+    "frontend",
+    "react",
+    "typescript"
+  ],
+  "author": "Your Name",
+  "license": "MIT"
+}