@opstel/modern-gauges 0.1.0

package/README.md

@@ -0,0 +1,110 @@
+# modern-gauge
+
+An animated half-circle SVG gauge component for React. Zero runtime dependencies beyond React itself.
+
+## Features
+
+- Smooth animated arc fill that interpolates from the previous value on each update
+- Gradient color progression across the arc and tick marks
+- Automatically generated minor tick marks between major labels
+- Responsive — fills its container via SVG `viewBox`
+- Optional card wrapper with shadow, or render bare into any layout
+
+## Installation
+
+```bash
+npm install modern-gauge
+```
+
+## Usage
+
+```jsx
+import { HalfGauge } from 'modern-gauge';
+
+function Dashboard() {
+  return (
+    <HalfGauge
+      value={72}
+      ticks={[0, 20, 40, 60, 80, 100]}
+      colors={['#f44336', '#ffeb3b', '#4caf50']}
+      title="CPU (%)"
+    />
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `number` | — | Current value to display |
+| `ticks` | `number[]` | `[0, 5, 10, 15, 20]` | Ordered scale values. First = min, last = max. Labels are rendered at each tick; minor ticks are inserted automatically between them. |
+| `colors` | `string[]` | `['#f44336', '#9c27b0']` | Two or more CSS colors forming the gradient from min to max. |
+| `title` | `string` | — | Optional label displayed below the value |
+| `withoutBackground` | `boolean` | `false` | When `true`, renders only the gauge SVG with no card wrapper. Use this when embedding inside your own container. |
+| `className` | `string` | — | CSS class applied to the card wrapper (ignored when `withoutBackground` is true) |
+| `style` | `object` | — | Inline styles merged into the card wrapper (ignored when `withoutBackground` is true) |
+
+## Examples
+
+### Minimal
+
+```jsx
+<HalfGauge value={12} />
+```
+
+### Custom scale and colors
+
+```jsx
+<HalfGauge
+  value={3500}
+  ticks={[0, 1000, 2000, 3000, 4000, 5000, 6000]}
+  colors={['#4caf50', '#ffeb3b', '#f44336']}
+  title="RPM"
+/>
+```
+
+### Embedded in a custom container (no card)
+
+```jsx
+<div style={{ width: 200, height: 130 }}>
+  <HalfGauge
+    value={55}
+    ticks={[0, 25, 50, 75, 100]}
+    colors={['#2196f3', '#e91e63']}
+    withoutBackground
+  />
+</div>
+```
+
+### Custom card size via style prop
+
+```jsx
+<HalfGauge
+  value={8}
+  ticks={[0, 2, 4, 6, 8, 10]}
+  title="Score"
+  style={{ width: '12rem', height: '10rem', flexGrow: 0 }}
+/>
+```
+
+## Tick behaviour
+
+The `ticks` array defines where major labels appear. Minor ticks are inserted automatically:
+
+- **≤ 5 major ticks** → 4 minor ticks per gap
+- **6–16 major ticks** → 2 minor ticks per gap
+- **> 16 major ticks** → no minor ticks; every other label is hidden to avoid crowding
+
+## Peer Dependencies
+
+```json
+{
+  "react": ">=17.0.0",
+  "react-dom": ">=17.0.0"
+}
+```
+
+## License
+
+MIT

package/dist/index.cjs.js

@@ -0,0 +1,17 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("react/jsx-runtime"),y=require("react");(function(){if(typeof document>"u")return;const a="__modern-half-gauge-styles__";if(document.getElementById(a))return;const o=document.createElement("style");o.id=a,o.textContent=`
+    @keyframes modern-gauge-fill-arc {
+      from { stroke-dasharray: var(--mg-initial-dash, 0) 500; }
+      to   { stroke-dasharray: var(--mg-final-dash, 0) 500; }
+    }
+    @keyframes modern-gauge-fill-tick {
+      from { stroke: #9e9e9e; }
+      to   { stroke: var(--mg-tick-color, #9e9e9e); }
+    }
+    .modern-gauge-arc {
+      animation: modern-gauge-fill-arc 1s ease-out forwards;
+    }
+    .modern-gauge-tick {
+      animation: modern-gauge-fill-tick 1s ease-out forwards;
+      animation-delay: var(--mg-tick-delay, 0s);
+    }
+  `,document.head.appendChild(o)})();const C=({value:h,colors:a,title:o,minMax:f})=>{const n=f||[0,5,10,15,20],m=n.at(0)??0,Y=n.at(-1)??1,g=h??m,x=y.useRef(`mg-${Math.random().toString(36).substring(2,9)}`).current,p=y.useRef(m);y.useEffect(()=>{const e=setTimeout(()=>{p.current=g},1e3);return()=>clearTimeout(e)},[g]);const j=Y-m||1,b=Math.min(1,Math.max(0,(p.current-m)/j)),v=Math.min(1,Math.max(0,(g-m)/j)),M=Math.PI*40,L=v*M,w=b*M,S=n.length>8;let c=[];if(n.length<17){const e=n.length<6?4:2,i=e+1;for(let r=0;r<n.length;r++)if(c.push({value:n[r],isMajor:!0}),r<n.length-1){const d=n[r],l=(n[r+1]-d)/i;for(let u=1;u<=e;u++)c.push({value:d+u*l,isMajor:!1})}}else c=n.map(e=>({value:e,isMajor:!0}));const I=c.filter(e=>e.isMajor),X=c.map((e,i)=>{const r=c.length-1,s=(i/r*180-180)*(Math.PI/180),l=36,u=e.isMajor?5:2.5,T=I.indexOf(e),F=e.isMajor&&(!S||T%2===0),R=50+l*Math.cos(s),A=45+l*Math.sin(s),E=50+(l-u)*Math.cos(s),G=45+(l-u)*Math.sin(s),k=l-10,P=50+k*Math.cos(s),W=45+k*Math.sin(s);return{value:e.value,innerX:E,innerY:G,outerX:R,outerY:A,labelX:P,labelY:W,showLabel:F}}),$=a&&a.length>=2?a:["#f44336","#9c27b0"];return t.jsx("div",{style:{height:"100%",width:"100%"},children:t.jsxs("div",{style:{width:"100%",height:"100%",position:"relative"},children:[t.jsxs("svg",{width:"100%",height:"100%",viewBox:"0 0 100 55",children:[t.jsx("defs",{children:t.jsx("linearGradient",{id:`gradient-${x}`,gradientUnits:"userSpaceOnUse",x1:10,y1:45,x2:90,y2:45,children:$.map((e,i)=>t.jsx("stop",{offset:`${i/($.length-1)*100}%`,stopColor:e},i))})}),t.jsx("path",{stroke:"#9e9e9e",strokeWidth:"3",strokeLinecap:"round",fill:"none",d:"M 10 45 A 40 40 0 1 1 90 45"}),t.jsx("path",{className:"modern-gauge-arc",fill:"none",strokeWidth:"3",stroke:`url(#gradient-${x})`,strokeLinecap:"round",strokeDashoffset:"0",style:{"--mg-initial-dash":`${w}`,"--mg-final-dash":`${L}`},d:"M 10 45 A 40 40 0 1 1 90 45"}),X.map((e,i)=>{const r=i/(X.length-1),d=r<=v,s=r;return t.jsxs("g",{children:[t.jsx("line",{x1:e.innerX,y1:e.innerY,x2:e.outerX,y2:e.outerY,strokeWidth:"1",strokeLinecap:"round",stroke:"#9e9e9e"}),t.jsx("line",{className:"modern-gauge-tick",x1:e.innerX,y1:e.innerY,x2:e.outerX,y2:e.outerY,strokeWidth:"1",strokeLinecap:"round",style:{"--mg-tick-color":`url(#gradient-${x})`,"--mg-tick-delay":d?`${s}s`:"0s",animationPlayState:d?"running":"paused"}}),e.showLabel&&t.jsx("text",{x:e.labelX,y:e.labelY,textAnchor:"middle",dominantBaseline:"middle",fontSize:"5",fill:"#9e9e9e",fontFamily:"sans-serif",children:e.value})]},e.value)})]}),t.jsxs("div",{style:{position:"absolute",top:"70%",left:"50%",transform:"translate(-50%, -50%)",textAlign:"center",pointerEvents:"none",whiteSpace:"nowrap"},children:[t.jsx("div",{style:{fontSize:"3rem",fontWeight:500,lineHeight:1.2},children:h}),o&&t.jsx("div",{style:{fontSize:"0.9rem",marginTop:"4px"},children:o})]})]},g)})},O=({value:h,colors:a,title:o,minMax:f})=>t.jsx(C,{value:h,colors:a,title:o,minMax:f});exports.HalfGauge=O;

package/dist/index.es.js

@@ -0,0 +1,198 @@
+import { jsx as t, jsxs as f } from "react/jsx-runtime";
+import { useRef as j, useEffect as V } from "react";
+(function() {
+  if (typeof document > "u") return;
+  const o = "__modern-half-gauge-styles__";
+  if (document.getElementById(o)) return;
+  const s = document.createElement("style");
+  s.id = o, s.textContent = `
+    @keyframes modern-gauge-fill-arc {
+      from { stroke-dasharray: var(--mg-initial-dash, 0) 500; }
+      to   { stroke-dasharray: var(--mg-final-dash, 0) 500; }
+    }
+    @keyframes modern-gauge-fill-tick {
+      from { stroke: #9e9e9e; }
+      to   { stroke: var(--mg-tick-color, #9e9e9e); }
+    }
+    .modern-gauge-arc {
+      animation: modern-gauge-fill-arc 1s ease-out forwards;
+    }
+    .modern-gauge-tick {
+      animation: modern-gauge-fill-tick 1s ease-out forwards;
+      animation-delay: var(--mg-tick-delay, 0s);
+    }
+  `, document.head.appendChild(s);
+})();
+const _ = ({ value: m, colors: o, title: s, minMax: p }) => {
+  const n = p || [0, 5, 10, 15, 20], h = n.at(0) ?? 0, b = n.at(-1) ?? 1, g = m ?? h, y = j(`mg-${Math.random().toString(36).substring(2, 9)}`).current, x = j(h);
+  V(() => {
+    const e = setTimeout(() => {
+      x.current = g;
+    }, 1e3);
+    return () => clearTimeout(e);
+  }, [g]);
+  const v = b - h || 1, L = Math.min(
+    1,
+    Math.max(0, (x.current - h) / v)
+  ), M = Math.min(
+    1,
+    Math.max(0, (g - h) / v)
+  ), X = Math.PI * 40, w = M * X, S = L * X, I = n.length > 8;
+  let c = [];
+  if (n.length < 17) {
+    const e = n.length < 6 ? 4 : 2, i = e + 1;
+    for (let r = 0; r < n.length; r++)
+      if (c.push({ value: n[r], isMajor: !0 }), r < n.length - 1) {
+        const d = n[r], l = (n[r + 1] - d) / i;
+        for (let u = 1; u <= e; u++)
+          c.push({ value: d + u * l, isMajor: !1 });
+      }
+  } else
+    c = n.map((e) => ({ value: e, isMajor: !0 }));
+  const F = c.filter((e) => e.isMajor), $ = c.map((e, i) => {
+    const r = c.length - 1, a = (i / r * 180 - 180) * (Math.PI / 180), l = 36, u = e.isMajor ? 5 : 2.5, T = F.indexOf(e), A = e.isMajor && (!I || T % 2 === 0), E = 50 + l * Math.cos(a), W = 45 + l * Math.sin(a), C = 50 + (l - u) * Math.cos(a), G = 45 + (l - u) * Math.sin(a), Y = l - 10, P = 50 + Y * Math.cos(a), R = 45 + Y * Math.sin(a);
+    return {
+      value: e.value,
+      innerX: C,
+      innerY: G,
+      outerX: E,
+      outerY: W,
+      labelX: P,
+      labelY: R,
+      showLabel: A
+    };
+  }), k = o && o.length >= 2 ? o : ["#f44336", "#9c27b0"];
+  return /* @__PURE__ */ t("div", { style: { height: "100%", width: "100%" }, children: /* @__PURE__ */ f(
+    "div",
+    {
+      style: { width: "100%", height: "100%", position: "relative" },
+      children: [
+        /* @__PURE__ */ f("svg", { width: "100%", height: "100%", viewBox: "0 0 100 55", children: [
+          /* @__PURE__ */ t("defs", { children: /* @__PURE__ */ t(
+            "linearGradient",
+            {
+              id: `gradient-${y}`,
+              gradientUnits: "userSpaceOnUse",
+              x1: 10,
+              y1: 45,
+              x2: 90,
+              y2: 45,
+              children: k.map((e, i) => /* @__PURE__ */ t(
+                "stop",
+                {
+                  offset: `${i / (k.length - 1) * 100}%`,
+                  stopColor: e
+                },
+                i
+              ))
+            }
+          ) }),
+          /* @__PURE__ */ t(
+            "path",
+            {
+              stroke: "#9e9e9e",
+              strokeWidth: "3",
+              strokeLinecap: "round",
+              fill: "none",
+              d: "M 10 45 A 40 40 0 1 1 90 45"
+            }
+          ),
+          /* @__PURE__ */ t(
+            "path",
+            {
+              className: "modern-gauge-arc",
+              fill: "none",
+              strokeWidth: "3",
+              stroke: `url(#gradient-${y})`,
+              strokeLinecap: "round",
+              strokeDashoffset: "0",
+              style: {
+                "--mg-initial-dash": `${S}`,
+                "--mg-final-dash": `${w}`
+              },
+              d: "M 10 45 A 40 40 0 1 1 90 45"
+            }
+          ),
+          $.map((e, i) => {
+            const r = i / ($.length - 1), d = r <= M, a = r;
+            return /* @__PURE__ */ f("g", { children: [
+              /* @__PURE__ */ t(
+                "line",
+                {
+                  x1: e.innerX,
+                  y1: e.innerY,
+                  x2: e.outerX,
+                  y2: e.outerY,
+                  strokeWidth: "1",
+                  strokeLinecap: "round",
+                  stroke: "#9e9e9e"
+                }
+              ),
+              /* @__PURE__ */ t(
+                "line",
+                {
+                  className: "modern-gauge-tick",
+                  x1: e.innerX,
+                  y1: e.innerY,
+                  x2: e.outerX,
+                  y2: e.outerY,
+                  strokeWidth: "1",
+                  strokeLinecap: "round",
+                  style: {
+                    "--mg-tick-color": `url(#gradient-${y})`,
+                    "--mg-tick-delay": d ? `${a}s` : "0s",
+                    animationPlayState: d ? "running" : "paused"
+                  }
+                }
+              ),
+              e.showLabel && /* @__PURE__ */ t(
+                "text",
+                {
+                  x: e.labelX,
+                  y: e.labelY,
+                  textAnchor: "middle",
+                  dominantBaseline: "middle",
+                  fontSize: "5",
+                  fill: "#9e9e9e",
+                  fontFamily: "sans-serif",
+                  children: e.value
+                }
+              )
+            ] }, e.value);
+          })
+        ] }),
+        /* @__PURE__ */ f(
+          "div",
+          {
+            style: {
+              position: "absolute",
+              top: "70%",
+              left: "50%",
+              transform: "translate(-50%, -50%)",
+              textAlign: "center",
+              pointerEvents: "none",
+              whiteSpace: "nowrap"
+            },
+            children: [
+              /* @__PURE__ */ t("div", { style: { fontSize: "3rem", fontWeight: 500, lineHeight: 1.2 }, children: m }),
+              s && /* @__PURE__ */ t(
+                "div",
+                {
+                  style: {
+                    fontSize: "0.9rem",
+                    marginTop: "4px"
+                  },
+                  children: s
+                }
+              )
+            ]
+          }
+        )
+      ]
+    },
+    g
+  ) });
+}, q = ({ value: m, colors: o, title: s, minMax: p }) => /* @__PURE__ */ t(_, { value: m, colors: o, title: s, minMax: p });
+export {
+  q as HalfGauge
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@opstel/modern-gauges",
+  "version": "0.1.0",
+  "description": "Animated half-circle gauges React component — zero runtime dependencies",
+  "keywords": [
+    "react",
+    "gauge",
+    "chart",
+    "svg",
+    "animation",
+    "meter",
+    "dashboard"
+  ],
+  "author": "Caleb <caleb.pope@opstel.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.es.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.es.js",
+      "require": "./dist/index.cjs.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=17.0.0",
+    "react-dom": ">=17.0.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.0.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "vite": "^5.0.0"
+  }
+}