Initial commit

.github/workflows/main.yml

@@ -0,0 +1,32 @@
+name: CI
+on: [push]
+jobs:
+  build:
+    name: Build, lint, and test on Node ${{ matrix.node }} and ${{ matrix.os }}
+
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        node: ['10.x', '12.x', '14.x']
+        os: [ubuntu-latest, windows-latest, macOS-latest]
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v2
+
+      - name: Use Node ${{ matrix.node }}
+        uses: actions/setup-node@v1
+        with:
+          node-version: ${{ matrix.node }}
+
+      - name: Install deps and build (with cache)
+        uses: bahmutov/npm-install@v1
+
+      - name: Lint
+        run: yarn lint
+
+      - name: Test
+        run: yarn test --ci --coverage --maxWorkers=2
+
+      - name: Build
+        run: yarn build

.github/workflows/size.yml

@@ -0,0 +1,12 @@
+name: size
+on: [pull_request]
+jobs:
+  size:
+    runs-on: ubuntu-latest
+    env:
+      CI_JOB_NUMBER: 1
+    steps:
+      - uses: actions/checkout@v1
+      - uses: andresz1/size-limit-action@v1
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -0,0 +1,5 @@
+*.log
+.DS_Store
+node_modules
+.cache
+dist

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Vlad Arbatov
+
+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.

README.md

@@ -0,0 +1,107 @@
+# react-performance-detector
+
+### Introduction
+
+**`react-pd`** is a React library designed to help developers automatically detect when a user's browser is experiencing performance issues such as throttling or lag. When performance issues are detected, the application can adapt to provide a smoother, more lightweight experience for the user.
+
+Modern websites often feature rich animations, high-resolution images, and interactive elements that can be resource-intensive, especially on older or low-powered devices. By using `react-pd`, you can detect when the user's browsing environment is struggling and adjust your UI dynamically to keep the user experience optimal, even under less-than-ideal conditions.
+
+### Key Features
+
+- **Frame Rate Monitoring**: Track frame rate (FPS) to identify if the user's device is struggling to keep up with animations or other tasks.
+- **Long Task Detection**: Use the `PerformanceObserver` API to monitor long-running tasks that could affect responsiveness.
+- **Customizable Parameters**: Easily adjust detection thresholds to suit your specific needs or let the library use its defaults.
+- **React Hooks**: Provides easy integration through a `usePerformance` hook to access lagging status wherever you need in your application.
+- **Fallback Handling**: You can optionally define custom behavior when the environment does not support performance detection features.
+
+Whether you're building a highly interactive web application or an e-commerce site, `react-pd` ensures your users enjoy the best experience, regardless of their hardware capabilities or the conditions under which they browse.
+
+
+## Quickstart: Basic Usage
+
+1. Install library with `npm i react-pd` or `yarn add react-pd`
+2. Use the `PerformanceProvider` and `usePerformance` Hook in your app
+
+### Example:
+```tsx
+import React from 'react';
+import { PerformanceProvider, usePerformance } from 'react-performance-detector';
+
+const MyComponent: React.FC = () => {
+  const isLagging = usePerformance(); // Use the usePerformance hook within any child component to get a boolean (isLagging) indicating whether the user is experiencing performance issues
+
+  return (
+    <div>
+      {isLagging ? ( // If isLagging is true, the application can switch to a lightweight version, reducing the load on the browser
+        <div>Rendering lightweight version...</div>
+      ) : (
+        <div>Rendering full, animated version...</div>
+      )}
+    </div>
+  );
+};
+
+const App: React.FC = () => {
+  return (
+    <PerformanceProvider>
+      // Wrap your components with the PerformanceProvider to enable performance monitoring throughout the app or a specific section of it
+      <MyComponent />
+    </PerformanceProvider>
+  );
+};
+
+export default App;
+```
+
+### Default Behavior
+With the default configuration, the `react-pd` library will:
+- Detect low frame rates (`fpsThreshold` of 20).
+- Monitor for long tasks exceeding 50ms.
+- Check performance every second (`checkInterval` of 1000ms).
+
+## Browser Requirements
+
+This library uses `PerformanceObserver` to detect performance issues in the browser. Please note the following:
+
+- The library **requires** a modern browser with support for `PerformanceObserver`. (Basically [all browsers since 2015](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceObserver) support it.) If this API is unavailable, throttling detection will be disabled, and a warning will be logged to the console.
+- If you are running in a non-browser environment (e.g., SSR), the hook will log an error and disable itself.
+
+## Handling Unsupported Environments
+
+If your target audience includes older browsers, you can:
+
+- Gracefully degrade features that depend on throttling detection.
+- Use a polyfill where applicable (note that polyfill support for `PerformanceObserver` may be limited).
+
+## Example with config and fallback behavior
+
+```tsx
+import React from "react";
+import { usePerformanceStatus, ThrottleDetectionConfig } from "react-pd";
+
+const MyComponent: React.FC = () => {
+  const config: ThrottleDetectionConfig = {
+    fpsThreshold: 20,
+    longTaskThreshold: 50,
+    checkInterval: 1000,
+    onFeatureNotAvailable: () => {
+      console.warn("Performance features are not available, running fallback behavior...");
+      // Here you could disable some animations, show a fallback UI, etc.
+    },
+  };
+
+  const isLagging = usePerformanceStatus(config);
+
+  return (
+    <div>
+      {isLagging ? (
+        <div>Rendering lightweight version...</div>
+      ) : (
+        <div>Rendering heavy, animated version...</div>
+      )}
+    </div>
+  );
+};
+
+export default MyComponent;
+```

example/.npmignore

@@ -0,0 +1,3 @@
+node_modules
+.cache
+dist

example/index.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
+    <title>Playground</title>
+  </head>
+
+  <body>
+    <div id="root"></div>
+    <script src="./index.tsx"></script>
+  </body>
+</html>

example/index.tsx

@@ -0,0 +1,14 @@
+import 'react-app-polyfill/ie11';
+import * as React from 'react';
+import * as ReactDOM from 'react-dom';
+import { Thing } from '../.';
+
+const App = () => {
+  return (
+    <div>
+      <Thing />
+    </div>
+  );
+};
+
+ReactDOM.render(<App />, document.getElementById('root'));

example/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "example",
+  "version": "1.0.0",
+  "main": "index.js",
+  "license": "MIT",
+  "scripts": {
+    "start": "parcel index.html",
+    "build": "parcel build index.html"
+  },
+  "dependencies": {
+    "react-app-polyfill": "^1.0.0"
+  },
+  "alias": {
+    "react": "../node_modules/react",
+    "react-dom": "../node_modules/react-dom/profiling",
+    "scheduler/tracing": "../node_modules/scheduler/tracing-profiling"
+  },
+  "devDependencies": {
+    "@types/react": "^16.9.11",
+    "@types/react-dom": "^16.8.4",
+    "parcel": "^1.12.3",
+    "typescript": "^3.4.5"
+  }
+}

example/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "allowSyntheticDefaultImports": false,
+    "target": "es5",
+    "module": "commonjs",
+    "jsx": "react",
+    "moduleResolution": "node",
+    "noImplicitAny": false,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "removeComments": true,
+    "strictNullChecks": true,
+    "preserveConstEnums": true,
+    "sourceMap": true,
+    "lib": ["es2015", "es2016", "dom"],
+    "types": ["node"]
+  }
+}

global.d.ts

@@ -0,0 +1 @@
+import '@testing-library/jest-dom/extend-expect';