@larose-ui/network 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 laRose contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+import { NetworkCondition } from '@larose-ui/core';
+
+interface NetworkState {
+    condition: NetworkCondition;
+    online: boolean;
+    effectiveType?: string;
+    downlink?: number;
+    rtt?: number;
+    /** Consecutive request failures in the current window */
+    failureCount?: number;
+}
+interface NetworkMonitorOptions {
+    slowThresholdMs?: number;
+    pollIntervalMs?: number;
+    /** Failures within window before condition becomes `failed` */
+    failureThreshold?: number;
+    /** How long `recovering` lasts after reconnect (ms) */
+    recoveringDurationMs?: number;
+}
+type NetworkListener = (state: NetworkState) => void;
+declare class NetworkMonitor {
+    private options;
+    private listeners;
+    private state;
+    private pollTimer?;
+    private recoveringTimer?;
+    private wasOffline;
+    private recoveringUntil;
+    private failureCount;
+    private onOnline;
+    private onOffline;
+    private onConnectionChange;
+    constructor(options?: NetworkMonitorOptions);
+    get current(): NetworkState;
+    subscribe(listener: NetworkListener): () => void;
+    /** Report a failed network/API request */
+    reportFailure(): void;
+    /** Report a successful request — clears failure streak */
+    reportSuccess(): void;
+    destroy(): void;
+    private handleOnline;
+    private readState;
+    private setCondition;
+    private update;
+    private attach;
+}
+declare function createNetworkMonitor(options?: NetworkMonitorOptions): NetworkMonitor;
+declare function isOnlineNetwork(condition: NetworkCondition): boolean;
+declare function isSlowNetwork(condition: NetworkCondition): boolean;
+declare function isDegradedNetwork(condition: NetworkCondition): boolean;
+declare function shouldUseSkeleton(condition: NetworkCondition): boolean;
+/** @deprecated Use isOnlineNetwork — `online` condition alias for `fast` */
+declare function normalizeNetworkCondition(condition: NetworkCondition): NetworkCondition;
+
+export { NetworkMonitor, type NetworkMonitorOptions, type NetworkState, createNetworkMonitor, isDegradedNetwork, isOnlineNetwork, isSlowNetwork, normalizeNetworkCondition, shouldUseSkeleton };

package/dist/index.js

@@ -0,0 +1,144 @@
+// src/index.ts
+function getConnection() {
+  if (typeof navigator === "undefined") return void 0;
+  return navigator.connection;
+}
+function resolveBaseCondition(online, connection, slowThresholdMs = 2e3) {
+  if (!online) return "offline";
+  const rtt = connection?.rtt;
+  const effectiveType = connection?.effectiveType;
+  if (rtt !== void 0 && rtt >= slowThresholdMs) return "high-latency";
+  if (effectiveType === "slow-2g" || effectiveType === "2g") return "slow";
+  if (effectiveType === "3g") return "intermittent";
+  return "fast";
+}
+var NetworkMonitor = class {
+  constructor(options = {}) {
+    this.options = options;
+    this.state = this.readState();
+    this.attach();
+  }
+  options;
+  listeners = /* @__PURE__ */ new Set();
+  state;
+  pollTimer;
+  recoveringTimer;
+  wasOffline = false;
+  recoveringUntil = 0;
+  failureCount = 0;
+  onOnline = () => this.handleOnline();
+  onOffline = () => this.update();
+  onConnectionChange = () => this.update();
+  get current() {
+    return this.state;
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    listener(this.state);
+    return () => this.listeners.delete(listener);
+  }
+  /** Report a failed network/API request */
+  reportFailure() {
+    const threshold = this.options.failureThreshold ?? 3;
+    this.failureCount += 1;
+    if (this.failureCount >= threshold && this.state.online) {
+      this.setCondition("failed");
+    }
+  }
+  /** Report a successful request — clears failure streak */
+  reportSuccess() {
+    this.failureCount = 0;
+    if (this.state.condition === "failed") {
+      this.update();
+    }
+  }
+  destroy() {
+    if (typeof window === "undefined") return;
+    window.removeEventListener("online", this.onOnline);
+    window.removeEventListener("offline", this.onOffline);
+    const connection = getConnection();
+    connection?.removeEventListener?.("change", this.onConnectionChange);
+    if (this.pollTimer) clearInterval(this.pollTimer);
+    if (this.recoveringTimer) clearTimeout(this.recoveringTimer);
+    this.listeners.clear();
+  }
+  handleOnline() {
+    if (this.wasOffline) {
+      this.recoveringUntil = Date.now() + (this.options.recoveringDurationMs ?? 5e3);
+      if (this.recoveringTimer) clearTimeout(this.recoveringTimer);
+      this.recoveringTimer = setTimeout(() => this.update(), this.options.recoveringDurationMs ?? 5e3);
+    }
+    this.wasOffline = false;
+    this.update();
+  }
+  readState() {
+    const online = typeof navigator === "undefined" ? true : navigator.onLine;
+    const connection = getConnection();
+    const base = resolveBaseCondition(
+      online,
+      connection,
+      this.options.slowThresholdMs
+    );
+    let condition = base;
+    if (!online) {
+      this.wasOffline = true;
+      condition = "offline";
+    } else if (Date.now() < this.recoveringUntil) {
+      condition = "recovering";
+    } else if (this.failureCount >= (this.options.failureThreshold ?? 3)) {
+      condition = "failed";
+    }
+    return {
+      online,
+      effectiveType: connection?.effectiveType,
+      downlink: connection?.downlink,
+      rtt: connection?.rtt,
+      failureCount: this.failureCount,
+      condition
+    };
+  }
+  setCondition(condition) {
+    this.state = { ...this.state, condition };
+    this.listeners.forEach((l) => l(this.state));
+  }
+  update() {
+    this.state = this.readState();
+    this.listeners.forEach((l) => l(this.state));
+  }
+  attach() {
+    if (typeof window === "undefined") return;
+    window.addEventListener("online", this.onOnline);
+    window.addEventListener("offline", this.onOffline);
+    const connection = getConnection();
+    connection?.addEventListener?.("change", this.onConnectionChange);
+    const interval = this.options.pollIntervalMs ?? 3e4;
+    this.pollTimer = setInterval(() => this.update(), interval);
+  }
+};
+function createNetworkMonitor(options) {
+  return new NetworkMonitor(options);
+}
+function isOnlineNetwork(condition) {
+  return condition === "online" || condition === "fast" || condition === "recovering";
+}
+function isSlowNetwork(condition) {
+  return condition === "slow" || condition === "intermittent" || condition === "high-latency";
+}
+function isDegradedNetwork(condition) {
+  return isSlowNetwork(condition) || condition === "failed" || condition === "offline";
+}
+function shouldUseSkeleton(condition) {
+  return isSlowNetwork(condition) || condition === "recovering";
+}
+function normalizeNetworkCondition(condition) {
+  return condition === "online" ? "fast" : condition;
+}
+export {
+  NetworkMonitor,
+  createNetworkMonitor,
+  isDegradedNetwork,
+  isOnlineNetwork,
+  isSlowNetwork,
+  normalizeNetworkCondition,
+  shouldUseSkeleton
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@larose-ui/network",
+  "version": "0.1.0",
+  "description": "Network condition detection for laRose UI platform",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@larose-ui/core": "0.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/larose-ui/larose.git",
+    "directory": "packages/network"
+  },
+  "keywords": [
+    "larose",
+    "react",
+    "ui-platform",
+    "design-system",
+    "saas"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}