react-circular-range 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yan
+
+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/README.md

@@ -0,0 +1,194 @@
+# react-circular-range
+
+A compact, touch- and mouse-friendly circular (rotary) range knob React component with CSS-module theming. Supports double-click to reset, and works well inside instrument UIs (pedals, mixers, synth panels).
+
+## Features
+
+* Double-click to reset to mid value
+* Themeable via CSS modules
+
+## Install
+
+```bash
+npm install react-circular-range
+# or
+yarn add react-circular-range
+```
+
+## Types
+
+```ts
+type StyleSlots =
+  | 'knob'
+  | 'knobRing'
+  | 'knobBackground'
+  | 'knobBackgroundPath'
+  | 'knobIndicator'
+  | 'knobCenter'
+  | 'active';
+
+export type CircularRangeThemeProps = Partial<Record<StyleSlots, string>>;
+
+export interface CircularRangeProps {
+  // defaults: 0 / 100
+  min?: number;
+  max?: number;
+
+  value?: number;
+  step?: number;
+  
+  onChange?: (value: number) => void;
+
+  // optional CSS module object mapping slot names (knob, knobRing, knobBackground, etc.) to class names
+  theme?: CircularRangeThemeProps;
+}
+```
+
+## Simple example with pedal
+
+```tsx
+import { CircularRange } from "react-circular-range";
+import React, { useState } from "react";
+
+export const SimplePedal: React.FC = () => {
+  const [params, setParams] = useState({
+    gain: 50,
+    freq: 1000,
+    min: 25,
+    drive: 0,
+  });
+
+  const update = (key: keyof typeof params) => (v: number) => setParams(p => ({ ...p, [key]: v }));
+
+  return (
+    <div style={{ display: 'flex', gap: '3rem', justifyContent: 'center', padding: '4rem' }}>
+      <Knob label="GAIN" value={params.gain} unit="%" onChange={update('gain')}/>
+      <Knob label="FREQ" value={params.freq} unit="Hz" onChange={update('freq')} format={f => f >= 1000 ? `${(f/1000).toFixed(1)}k` : f.toString()} />
+      <Knob label="MIN"  value={params.min}  unit="%" onChange={update('min')} />
+      <Knob label="DRIVE" value={params.drive} unit="dB" onChange={update('drive')} format={d => `${d > 0 ? '+' : ''}${d}`} />
+    </div>
+  );
+};
+
+const Knob: React.FC<{ label: string; value: number; unit: string; onChange: (v: number) => void; format?: (v: number) => string }> = ({ label, value, unit, onChange, format = String }) => (
+  <div style={{ textAlign: 'center' }}>
+    <CircularRange
+      min={unit === 'Hz' ? 20 : unit === 'dB' ? -20 : 0}
+      max={unit === 'Hz' ? 20000 : unit === 'dB' ? 20 : 100}
+      step={unit === 'Hz' ? 10 : 1}
+      value={value}
+      onChange={onChange}
+    />
+    <div style={{ marginTop: '1rem', color: '#fff', fontFamily: 'monospace' }}>
+      <div style={{ fontSize: '0.75rem', opacity: 0.7 }}>{label}</div>
+      <div style={{ fontSize: '1.1rem', fontWeight: 'bold' }}>{format(value)}{unit}</div>
+    </div>
+  </div>
+);
+
+export const App = () => {
+  return <SimplePedal />
+}
+```
+
+## Example with style override (neon)
+
+```css
+/* neon.module.css */
+.knob {
+    width: 70px;
+    height: 70px;
+    position: relative;
+    cursor: pointer;
+}
+.knobRing {
+    width: 100%;
+    height: 100%;
+    border: 2px solid #00ffcc;
+    border-radius: 50%;
+    background: #0a0a0a;
+    box-shadow: 0 0 10px rgba(0, 255, 204, 0.5);
+}
+.knobBackground {
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    pointer-events: none;
+    transform: rotate(-135deg);
+}
+.knobBackgroundPath {
+    fill: none;
+    stroke: #00ffcc;
+    stroke-width: 3;
+    stroke-linecap: round;
+    stroke-dasharray: 113.1;
+    stroke-dashoffset: 113.1;
+    filter: drop-shadow(0 0 3px rgba(0, 255, 204, 0.9));
+}
+.knobIndicator {
+    position: absolute;
+    width: 4px;
+    height: 22px;
+    background: linear-gradient(to bottom, #00ffcc, #00b3ff);
+    top: 4px;
+    left: 50%;
+    transform-origin: center 31px;
+    transform: translateX(-50%) rotate(-135deg);
+    border-radius: 1px;
+    box-shadow: 0 0 8px rgba(0, 255, 204, 0.8);
+}
+.knobCenter {
+    position: absolute;
+    width: 20px;
+    height: 20px;
+    background: #000000;
+    border-radius: 50%;
+    top: 50%;
+    left: 50%;
+    transform: translate(-50%, -50%);
+    box-shadow: 0 0 5px rgba(0, 255, 204, 0.5);
+}
+/* Hover states */
+.knob:hover .knobRing {
+    border-color: #00ff88;
+    box-shadow: 0 0 15px rgba(0, 255, 204, 0.7);
+}
+.knob:hover .knobIndicator {
+    background: linear-gradient(to bottom, #00ff88, #00ccff);
+    box-shadow: 0 0 12px rgba(0, 255, 204, 1);
+}
+/* Active states */
+.knob.active .knobRing {
+    border-color: #00ff88;
+    box-shadow: 0 0 20px rgba(0, 255, 204, 0.9);
+}
+.knob.active .knobIndicator {
+    background: linear-gradient(to bottom, #00ff88, #00ccff);
+    box-shadow: 0 0 15px rgba(0, 255, 204, 1);
+}
+.knob.active .knobBackgroundPath {
+    stroke: #00ff88;
+    filter: drop-shadow(0 0 5px rgba(0, 255, 204, 1));
+}
+```
+
+## Import and pass as a prop
+
+```tsx
+import neonStyles from "./neon.module.css"
+
+// ...
+
+<CircularRange
+  min={unit === 'Hz' ? 20 : unit === 'dB' ? -20 : 0}
+  max={unit === 'Hz' ? 20000 : unit === 'dB' ? 20 : 100}
+  step={unit === 'Hz' ? 10 : 1}
+  value={value}
+  onChange={onChange}
+
+  theme={neonStyles} // <---
+/>
+
+```

package/dist/index.css

@@ -0,0 +1,110 @@
+/* src/CircularRange.module.css */
+.knob {
+  width: 65px;
+  height: 65px;
+  position: relative;
+  cursor: pointer;
+  user-select: none;
+}
+.knobRing {
+  width: 100%;
+  height: 100%;
+  border: 3px solid #333;
+  border-radius: 50%;
+  background:
+    linear-gradient(
+      145deg,
+      #1a1a1a,
+      #252525);
+  box-shadow:
+    inset 2px 2px 5px rgba(0, 0, 0, 0.5),
+    inset -2px -2px 5px rgba(60, 60, 60, 0.1),
+    0 4px 8px rgba(0, 0, 0, 0.3);
+  transition: border-color 0.2s ease, box-shadow 0.2s ease;
+}
+.knobBackground {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  pointer-events: none;
+  transform: rotate(-135deg);
+}
+.knobBackgroundPath {
+  fill: none;
+  stroke: #8b5cf6;
+  stroke-width: 3.5;
+  stroke-linecap: round;
+  stroke-dasharray: 113.1;
+  stroke-dashoffset: 113.1;
+  transition: stroke-dashoffset 0.1s ease-out;
+  filter: drop-shadow(0 0 3px rgba(139, 92, 246, 0.7));
+}
+.knobIndicator {
+  position: absolute;
+  width: 4px;
+  height: 20px;
+  background:
+    linear-gradient(
+      to bottom,
+      #8b5cf6,
+      #c084fc);
+  top: 5px;
+  left: 50%;
+  transform-origin: center 27.5px;
+  transform: translateX(-50%) rotate(-135deg);
+  border-radius: 2px;
+  z-index: 2;
+  box-shadow: 0 0 6px rgba(139, 92, 246, 0.8);
+}
+.knobCenter {
+  position: absolute;
+  width: 18px;
+  height: 18px;
+  background:
+    radial-gradient(
+      circle,
+      #0a0a0a,
+      #1a1a1a);
+  border-radius: 50%;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  box-shadow: inset 1px 1px 3px rgba(0, 0, 0, 0.7), 0 1px 2px rgba(139, 92, 246, 0.3);
+  z-index: 3;
+}
+.knob:hover .knobRing {
+  border-color: #8b5cf6;
+  box-shadow:
+    inset 2px 2px 5px rgba(0, 0, 0, 0.5),
+    inset -2px -2px 5px rgba(60, 60, 60, 0.1),
+    0 4px 12px rgba(139, 92, 246, 0.4);
+}
+.knob:hover .knobIndicator {
+  background:
+    linear-gradient(
+      to bottom,
+      #a78bfa,
+      #c084fc);
+  box-shadow: 0 0 8px rgba(167, 139, 250, 0.9);
+}
+.knob.active .knobRing {
+  border-color: #a78bfa;
+  box-shadow:
+    inset 2px 2px 5px rgba(0, 0, 0, 0.6),
+    inset -2px -2px 5px rgba(60, 60, 60, 0.15),
+    0 4px 16px rgba(167, 139, 250, 0.5);
+}
+.knob.active .knobIndicator {
+  background:
+    linear-gradient(
+      to bottom,
+      #a78bfa,
+      #c084fc);
+  box-shadow: 0 0 10px rgba(167, 139, 250, 1);
+}
+.knob.active .knobBackgroundPath {
+  stroke: #a78bfa;
+  filter: drop-shadow(0 0 4px rgba(167, 139, 250, 0.9));
+}

package/dist/index.d.mts

@@ -0,0 +1,15 @@
+import React from 'react';
+
+type StyleSlots = 'knob' | 'knobRing' | 'knobBackground' | 'knobBackgroundPath' | 'knobIndicator' | 'knobCenter' | 'active';
+type CircularRangeThemeProps = Partial<Record<StyleSlots, string>>;
+interface CircularRangeProps {
+    min?: number;
+    max?: number;
+    value?: number;
+    step?: number;
+    onChange?: (value: number) => void;
+    theme?: CircularRangeThemeProps;
+}
+declare const CircularRange: React.FC<CircularRangeProps>;
+
+export { CircularRange, type CircularRangeProps, type CircularRangeThemeProps, type StyleSlots };

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import React from 'react';
+
+type StyleSlots = 'knob' | 'knobRing' | 'knobBackground' | 'knobBackgroundPath' | 'knobIndicator' | 'knobCenter' | 'active';
+type CircularRangeThemeProps = Partial<Record<StyleSlots, string>>;
+interface CircularRangeProps {
+    min?: number;
+    max?: number;
+    value?: number;
+    step?: number;
+    onChange?: (value: number) => void;
+    theme?: CircularRangeThemeProps;
+}
+declare const CircularRange: React.FC<CircularRangeProps>;
+
+export { CircularRange, type CircularRangeProps, type CircularRangeThemeProps, type StyleSlots };

package/dist/index.js

@@ -0,0 +1,159 @@
+"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, {
+  CircularRange: () => CircularRange
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/CircularRange.tsx
+var import_react = require("react");
+
+// src/CircularRange.module.css
+var CircularRange_default = {};
+
+// src/CircularRange.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+var ARC_LENGTH = 113.1;
+var CircularRange = ({
+  min = 0,
+  max = 100,
+  value = 0,
+  step = 0.01,
+  onChange,
+  theme = CircularRange_default
+}) => {
+  const knobRef = (0, import_react.useRef)(null);
+  const [internalValue, setInternalValue] = (0, import_react.useState)(value);
+  const [isActive, setIsActive] = (0, import_react.useState)(false);
+  const startY = (0, import_react.useRef)(0);
+  const startValue = (0, import_react.useRef)(0);
+  const sensitivity = 0.01;
+  (0, import_react.useEffect)(() => {
+    setInternalValue(value);
+  }, [value]);
+  const clamp = (v) => Math.min(max, Math.max(min, v));
+  const getNormalizedValue = (0, import_react.useCallback)(
+    (v) => {
+      return (v - min) / (max - min);
+    },
+    [min, max]
+  );
+  const setValue = (0, import_react.useCallback)(
+    (v) => {
+      let next = clamp(v);
+      if (step > 0) {
+        next = Math.round(next / step) * step;
+      }
+      setInternalValue(next);
+      onChange?.(next);
+    },
+    [min, max, step, onChange]
+  );
+  const handleStart = (e) => {
+    e.preventDefault();
+    setIsActive(true);
+    const clientY = "touches" in e ? e.touches[0].clientY : e.clientY;
+    startY.current = clientY;
+    startValue.current = internalValue;
+  };
+  const handleMove = (e) => {
+    if (!isActive) return;
+    e.preventDefault();
+    const clientY = "touches" in e ? e.touches[0].clientY : e.clientY;
+    const deltaY = startY.current - clientY;
+    const deltaValue = deltaY * sensitivity * (max - min);
+    setValue(startValue.current + deltaValue);
+  };
+  const handleEnd = () => {
+    setIsActive(false);
+  };
+  const handleDoubleClick = () => {
+    setValue((min + max) / 2);
+  };
+  (0, import_react.useEffect)(() => {
+    const el = knobRef.current;
+    if (!el) return;
+    el.addEventListener("mousedown", handleStart);
+    el.addEventListener("touchstart", handleStart);
+    document.addEventListener("mousemove", handleMove);
+    document.addEventListener("touchmove", handleMove);
+    document.addEventListener("mouseup", handleEnd);
+    document.addEventListener("touchend", handleEnd);
+    el.addEventListener("dblclick", handleDoubleClick);
+    return () => {
+      el.removeEventListener("mousedown", handleStart);
+      el.removeEventListener("touchstart", handleStart);
+      document.removeEventListener("mousemove", handleMove);
+      document.removeEventListener("touchmove", handleMove);
+      document.removeEventListener("mouseup", handleEnd);
+      document.removeEventListener("touchend", handleEnd);
+      el.removeEventListener("dblclick", handleDoubleClick);
+    };
+  }, [handleMove, isActive]);
+  const normalized = getNormalizedValue(internalValue);
+  const rotation = normalized * 270 - 135;
+  const dashOffset = ARC_LENGTH - normalized * ARC_LENGTH;
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    "div",
+    {
+      ref: knobRef,
+      className: `${theme.knob} ${isActive ? theme.active : ""}`,
+      children: /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: `${theme.knobRing}`, children: [
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+          "svg",
+          {
+            className: `${theme.knobBackground}`,
+            viewBox: "0 0 60 60",
+            children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+              "path",
+              {
+                className: `${theme.knobBackgroundPath}`,
+                d: "M 30 6 A 24 24 0 1 1 6 30",
+                strokeDasharray: ARC_LENGTH,
+                strokeDashoffset: dashOffset
+              }
+            )
+          }
+        ),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+          "div",
+          {
+            className: `${theme.knobIndicator}`,
+            style: {
+              transform: `translateX(-50%) rotate(${rotation}deg)`
+            }
+          }
+        ),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+          "div",
+          {
+            className: `${theme.knobCenter}`
+          }
+        )
+      ] })
+    }
+  );
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CircularRange
+});

package/dist/index.mjs

@@ -0,0 +1,137 @@
+// src/CircularRange.tsx
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState
+} from "react";
+
+// src/CircularRange.module.css
+var CircularRange_default = {};
+
+// src/CircularRange.tsx
+import { jsx, jsxs } from "react/jsx-runtime";
+var ARC_LENGTH = 113.1;
+var CircularRange = ({
+  min = 0,
+  max = 100,
+  value = 0,
+  step = 0.01,
+  onChange,
+  theme = CircularRange_default
+}) => {
+  const knobRef = useRef(null);
+  const [internalValue, setInternalValue] = useState(value);
+  const [isActive, setIsActive] = useState(false);
+  const startY = useRef(0);
+  const startValue = useRef(0);
+  const sensitivity = 0.01;
+  useEffect(() => {
+    setInternalValue(value);
+  }, [value]);
+  const clamp = (v) => Math.min(max, Math.max(min, v));
+  const getNormalizedValue = useCallback(
+    (v) => {
+      return (v - min) / (max - min);
+    },
+    [min, max]
+  );
+  const setValue = useCallback(
+    (v) => {
+      let next = clamp(v);
+      if (step > 0) {
+        next = Math.round(next / step) * step;
+      }
+      setInternalValue(next);
+      onChange?.(next);
+    },
+    [min, max, step, onChange]
+  );
+  const handleStart = (e) => {
+    e.preventDefault();
+    setIsActive(true);
+    const clientY = "touches" in e ? e.touches[0].clientY : e.clientY;
+    startY.current = clientY;
+    startValue.current = internalValue;
+  };
+  const handleMove = (e) => {
+    if (!isActive) return;
+    e.preventDefault();
+    const clientY = "touches" in e ? e.touches[0].clientY : e.clientY;
+    const deltaY = startY.current - clientY;
+    const deltaValue = deltaY * sensitivity * (max - min);
+    setValue(startValue.current + deltaValue);
+  };
+  const handleEnd = () => {
+    setIsActive(false);
+  };
+  const handleDoubleClick = () => {
+    setValue((min + max) / 2);
+  };
+  useEffect(() => {
+    const el = knobRef.current;
+    if (!el) return;
+    el.addEventListener("mousedown", handleStart);
+    el.addEventListener("touchstart", handleStart);
+    document.addEventListener("mousemove", handleMove);
+    document.addEventListener("touchmove", handleMove);
+    document.addEventListener("mouseup", handleEnd);
+    document.addEventListener("touchend", handleEnd);
+    el.addEventListener("dblclick", handleDoubleClick);
+    return () => {
+      el.removeEventListener("mousedown", handleStart);
+      el.removeEventListener("touchstart", handleStart);
+      document.removeEventListener("mousemove", handleMove);
+      document.removeEventListener("touchmove", handleMove);
+      document.removeEventListener("mouseup", handleEnd);
+      document.removeEventListener("touchend", handleEnd);
+      el.removeEventListener("dblclick", handleDoubleClick);
+    };
+  }, [handleMove, isActive]);
+  const normalized = getNormalizedValue(internalValue);
+  const rotation = normalized * 270 - 135;
+  const dashOffset = ARC_LENGTH - normalized * ARC_LENGTH;
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      ref: knobRef,
+      className: `${theme.knob} ${isActive ? theme.active : ""}`,
+      children: /* @__PURE__ */ jsxs("div", { className: `${theme.knobRing}`, children: [
+        /* @__PURE__ */ jsx(
+          "svg",
+          {
+            className: `${theme.knobBackground}`,
+            viewBox: "0 0 60 60",
+            children: /* @__PURE__ */ jsx(
+              "path",
+              {
+                className: `${theme.knobBackgroundPath}`,
+                d: "M 30 6 A 24 24 0 1 1 6 30",
+                strokeDasharray: ARC_LENGTH,
+                strokeDashoffset: dashOffset
+              }
+            )
+          }
+        ),
+        /* @__PURE__ */ jsx(
+          "div",
+          {
+            className: `${theme.knobIndicator}`,
+            style: {
+              transform: `translateX(-50%) rotate(${rotation}deg)`
+            }
+          }
+        ),
+        /* @__PURE__ */ jsx(
+          "div",
+          {
+            className: `${theme.knobCenter}`
+          }
+        )
+      ] })
+    }
+  );
+};
+export {
+  CircularRange
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "react-circular-range",
+  "version": "1.0.0",
+  "description": "Simple VST-like circular slider/range.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/executable1210/react-circular-range.git"
+  },
+  "homepage": "https://github.com/executable1210/react-circular-range",
+  "author": {
+    "name": "exec",
+    "url": "https://github.com/executable1210"
+  },
+  "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"
+  ],
+  "keywords": [
+    "slider",
+    "round-slider",
+    "round-range",
+    "circular-slider",
+    "circular-range",
+    "circle-slider",
+    "circe-range"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts"
+  },
+  "peerDependencies": {
+    "react": ">=16 <20",
+    "react-dom": ">=16 <20"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  }
+}