@supermousejs/utils 2.1.1 → 2.3.0

package/src/dom.ts

@@ -1,131 +1,145 @@
-
-/**
- * Applies a dictionary of styles to an HTMLElement.
- */
-export function applyStyles(el: HTMLElement, styles: Partial<CSSStyleDeclaration>) {
-  Object.assign(el.style, styles);
-}
-
-// WeakMap to store previous styles for elements to prevent DOM thrashing
-const styleCache = new WeakMap<HTMLElement, Record<string, string | number>>();
-
-/**
- * Smart Style Setter.
- * Only writes to the DOM if the value has actually changed.
- */
-export function setStyle(el: HTMLElement, property: keyof CSSStyleDeclaration, value: string | number) {
-  let cache = styleCache.get(el);
-  if (!cache) {
-    cache = {};
-    styleCache.set(el, cache);
-  }
-
-  // Only write to DOM if value changed
-  if (cache[property as string] !== value) {
-    // @ts-ignore - Dynamic access
-    el.style[property] = value;
-    cache[property as string] = value;
-  }
-}
-
-/**
- * Universal Transform Setter.
- * Handles centering (-50%) automatically.
- * 
- * @param el The element
- * @param x X Position (px)
- * @param y Y Position (px)
- * @param rotation Rotation (deg) - Default 0
- * @param scaleX Scale X - Default 1
- * @param scaleY Scale Y - Default 1
- * @param skewX Skew X (deg) - Default 0
- * @param skewY Skew Y (deg) - Default 0
- */
-export function setTransform(
-  el: HTMLElement, 
-  x: number, 
-  y: number, 
-  rotation: number = 0, 
-  scaleX: number = 1, 
-  scaleY: number = 1,
-  skewX: number = 0,
-  skewY: number = 0
-) {
-  el.style.transform = `
-    translate3d(${x}px, ${y}px, 0) 
-    translate(-50%, -50%) 
-    rotate(${rotation}deg) 
-    skew(${skewX}deg, ${skewY}deg)
-    scale(${scaleX}, ${scaleY})
-  `;
-}
-
-/**
- * Calculates the bounding rectangle of an element relative to a container.
- * Useful for logic plugins when the cursor is confined to a specific div.
- */
-export function projectRect(element: HTMLElement, container: HTMLElement = document.body): DOMRect {
-  const rect = element.getBoundingClientRect();
-
-  if (container !== document.body) {
-    const containerRect = container.getBoundingClientRect();
-    const x = rect.left - containerRect.left;
-    const y = rect.top - containerRect.top;
-
-    return {
-      x,
-      y,
-      width: rect.width,
-      height: rect.height,
-      top: y,
-      left: x,
-      right: x + rect.width,
-      bottom: y + rect.height,
-      toJSON: () => ({})
-    } as DOMRect;
-  }
-
-  return rect;
-}
-
-/**
- * Creates a standard Supermouse actor element with optimal performance settings.
- * Includes absolute positioning, pointer-events: none, and will-change: transform.
- * 
- * @param tagName The HTML tag to create (default: 'div')
- */
-export function createActor(tagName: string = 'div'): HTMLElement {
-  const el = document.createElement(tagName);
-  applyStyles(el, {
-    position: 'absolute',
-    top: '0',
-    left: '0',
-    pointerEvents: 'none',
-    boxSizing: 'border-box',
-    display: 'block',
-    willChange: 'transform'
-  });
-  return el;
-}
-
-/**
- * Creates a circular HTML div using the standard actor base.
- */
-export function createCircle(size: number, color: string): HTMLDivElement {
-  const el = createActor('div') as HTMLDivElement;
-  applyStyles(el, {
-    width: `${size}px`,
-    height: `${size}px`,
-    borderRadius: '50%',
-    backgroundColor: color,
-  });
-  return el;
-}
-
-/**
- * Legacy alias for createActor.
- * @deprecated Use createActor() instead.
- */
-export function createDiv(): HTMLDivElement {
-  return createActor('div') as HTMLDivElement;
-}
+/**
+ * Injects global CSS styles into the document head safely.
+ * Checks for existing IDs to prevent duplication during SPA routing or HMR.
+ *
+ * @param id A unique identifier for this style block
+ * @param css A string of CSS rules to inject.
+ */
+export const injectStyles = (id: string, css: string) => {
+  if (typeof document === "undefined") return;
+  if (document.getElementById(id)) return;
+
+  const style = document.createElement("style");
+  style.id = id;
+  style.innerHTML = css;
+  document.head.appendChild(style);
+};
+
+// WeakMap to store previous styles for elements to prevent DOM thrashing
+const styleCache = new WeakMap<HTMLElement, Record<string, string | number>>();
+
+/**
+ * Smart Style Setter (Batch).
+ * Only writes to the DOM if the value has actually changed.
+ * @param el The element to style
+ * @param styles An object of CSS properties and values
+ */
+export function applyStyles(el: HTMLElement, styles: Partial<CSSStyleDeclaration>) {
+  if (typeof document === "undefined" || !el) return;
+
+  let cache = styleCache.get(el);
+  if (!cache) {
+    cache = {};
+    styleCache.set(el, cache);
+  }
+
+  for (const prop in styles) {
+    const value = (styles as any)[prop];
+    if (cache[prop] !== value) {
+      (el.style as any)[prop] = value;
+      cache[prop] = value;
+    }
+  }
+}
+
+/**
+ * Smart Style Setter (Single).
+ * Proxies to applyStyles for consistency.
+ * @param el The element to style
+ * @param property The CSS property to set
+ * @param value The value to set for the property
+ */
+export function setStyle(
+  el: HTMLElement,
+  property: keyof CSSStyleDeclaration,
+  value: string | number
+) {
+  applyStyles(el, { [property]: value } as any);
+}
+
+/**
+ * Universal Transform Setter.
+ * Handles centering (-50%) automatically.
+ *
+ * @param el The element
+ * @param x X Position (px)
+ * @param y Y Position (px)
+ * @param rotation Rotation (deg) - Default 0
+ * @param scaleX Scale X - Default 1
+ * @param scaleY Scale Y - Default 1
+ * @param skewX Skew X (deg) - Default 0
+ * @param skewY Skew Y (deg) - Default 0
+ */
+export function setTransform(
+  el: HTMLElement,
+  x: number,
+  y: number,
+  rotation: number = 0,
+  scaleX: number = 1,
+  scaleY: number = 1,
+  skewX: number = 0,
+  skewY: number = 0
+) {
+  const transform = `translate3d(${x}px, ${y}px, 0) translate(-50%, -50%) rotate(${rotation}deg) skew(${skewX}deg, ${skewY}deg) scale(${scaleX}, ${scaleY})`;
+
+  setStyle(el, "transform", transform);
+}
+
+/**
+ * Calculates the bounding rectangle of an element relative to a container.
+ */
+export function projectRect(element: HTMLElement, container: HTMLElement = document.body): DOMRect {
+  const rect = element.getBoundingClientRect();
+
+  if (container !== document.body) {
+    const containerRect = container.getBoundingClientRect();
+    const x = rect.left - containerRect.left;
+    const y = rect.top - containerRect.top;
+
+    return new DOMRect(x, y, rect.width, rect.height);
+  }
+
+  return rect;
+}
+
+/**
+ * Creates a standard Supermouse actor element with optimal performance settings.
+ * Includes absolute positioning, pointer-events: none, and will-change: transform.
+ *
+ * @param tagName The HTML tag to create (default: 'div')
+ */
+export function createActor(tagName: string = "div"): HTMLElement {
+  const el = document.createElement(tagName);
+  applyStyles(el, {
+    position: "absolute",
+    top: "0",
+    left: "0",
+    pointerEvents: "none",
+    boxSizing: "border-box",
+    display: "block",
+    willChange: "transform"
+  });
+  return el;
+}
+
+/**
+ * Creates a circular HTML div using the standard actor base.
+ */
+export function createCircle(size: number, color: string): HTMLDivElement {
+  const el = createActor("div") as HTMLDivElement;
+  applyStyles(el, {
+    width: `${size}px`,
+    height: `${size}px`,
+    borderRadius: "50%",
+    backgroundColor: color
+  });
+  return el;
+}
+
+/**
+ * Legacy alias for createActor.
+ * @deprecated Use createActor() instead.
+ */
+export function createDiv(): HTMLDivElement {
+  return createActor("div") as HTMLDivElement;
+}

package/src/effects.ts

@@ -1,35 +1,34 @@
-
-import { dist, angle, clamp } from './math';
-
-/**
- * Calculates Rotation and Scale based on velocity to create a "Squash and Stretch" effect.
- * 
- * @param vx Velocity X
- * @param vy Velocity Y
- * @param intensity Stretch factor (default: 0.004)
- * @param maxStretch Max stretch percentage (default: 0.5 = 150% length)
- */
-export function getVelocityDistortion(vx: number, vy: number, intensity = 0.004, maxStretch = 0.5) {
-  const speed = dist(vx, vy);
-  
-  // Deadzone: If moving too slow, don't rotate (prevents jittering at rest)
-  if (speed < 0.1) {
-    return { rotation: 0, scaleX: 1, scaleY: 1 };
-  }
-
-  // 1. Point towards movement
-  const rotation = angle(vx, vy);
-
-  // 2. Stretch based on speed
-  const stretch = clamp(speed * intensity, 0, maxStretch);
-  
-  // 3. Scale X grows, Scale Y shrinks (to preserve volume-ish)
-  const scaleX = 1 + stretch;
-  const scaleY = 1 - (stretch * 0.5); // Squash factor
-
-  return {
-    rotation,
-    scaleX,
-    scaleY
-  };
-}
+import { dist, angle, clamp } from "./math";
+
+/**
+ * Calculates Rotation and Scale based on velocity to create a "Squash and Stretch" effect.
+ *
+ * @param vx Velocity X
+ * @param vy Velocity Y
+ * @param intensity Stretch factor (default: 0.004)
+ * @param maxStretch Max stretch percentage (default: 0.5 = 150% length)
+ */
+export function getVelocityDistortion(vx: number, vy: number, intensity = 0.004, maxStretch = 0.5) {
+  const speed = dist(vx, vy);
+
+  // Deadzone: If moving too slow, don't rotate (prevents jittering at rest)
+  if (speed < 0.1) {
+    return { rotation: 0, scaleX: 1, scaleY: 1 };
+  }
+
+  // 1. Point towards movement
+  const rotation = angle(vx, vy);
+
+  // 2. Stretch based on speed
+  const stretch = clamp(speed * intensity, 0, maxStretch);
+
+  // 3. Scale X grows, Scale Y shrinks (to preserve volume-ish)
+  const scaleX = 1 + stretch;
+  const scaleY = 1 - stretch * 0.5; // Squash factor
+
+  return {
+    rotation,
+    scaleX,
+    scaleY
+  };
+}

package/src/index.ts

@@ -1,10 +1,10 @@
-import * as math from './math';
-import * as dom from './dom';
-import * as effects from './effects';
-
-export { math, dom, effects };
-export * from './layers';
-export * from './css';
-export * from './plugin';
-export * from './options';
-export * from './doctor';
+import * as math from "./math";
+import * as dom from "./dom";
+import * as effects from "./effects";
+
+export { math, dom, effects };
+export * from "./layers";
+export * from "./css";
+export * from "./plugin";
+export * from "./options";
+export * from "./doctor";

package/src/layers.ts

@@ -1,17 +1,17 @@
-/**
- * Standard Z-Index layers for the Supermouse ecosystem.
- * Relative to the Supermouse Container.
- */
-export const Layers = {
-  /** The top-most layer. For text, tooltips, and crucial UI. */
-  OVERLAY: '400', 
-  
-  /** The main cursor layer. For the primary Dot/Pointer. */
-  CURSOR: '300',
-  
-  /** The secondary layer. For Rings, brackets, or followers. */
-  FOLLOWER: '200',
-  
-  /** The background layer. For trails, sparkles, and particles. */
-  TRACE: '100',
-} as const;
+/**
+ * Standard Z-Index layers for the Supermouse ecosystem.
+ * Relative to the Supermouse Container.
+ */
+export const Layers = {
+  /** The top-most layer. For text, tooltips, and crucial UI. */
+  OVERLAY: "400",
+
+  /** The main cursor layer. For the primary Dot/Pointer. */
+  CURSOR: "300",
+
+  /** The secondary layer. For Rings, brackets, or followers. */
+  FOLLOWER: "200",
+
+  /** The background layer. For trails, sparkles, and particles. */
+  TRACE: "100"
+} as const;

package/src/math.ts

@@ -1,60 +1,60 @@
-/**
- * Linear Interpolation between two values.
- */
-export function lerp(start: number, end: number, factor: number): number {
-  return start + (end - start) * factor;
-}
-
-/**
- * Frame-rate independent damping (Time-based Lerp).
- * Ensures smooth animation consistent across 60hz, 120hz, etc.
- * 
- * @param a Current value
- * @param b Target value
- * @param lambda Smoothing factor (approx 1-20). Higher is faster.
- * @param dt Delta time in seconds (not milliseconds)
- */
-export function damp(a: number, b: number, lambda: number, dt: number): number {
-  return lerp(a, b, 1 - Math.exp(-lambda * dt));
-}
-
-/**
- * Linear Interpolation between two angles in degrees, taking the shortest path.
- * Handles wrap-around at 360 degrees.
- */
-export function lerpAngle(start: number, end: number, factor: number): number {
-  const diff = ((((end - start) % 360) + 540) % 360) - 180;
-  return start + diff * factor;
-}
-
-/**
- * Returns a random number between min and max.
- * Usage: math.random(10, 20) -> 14.5
- */
-export function random(min: number, max: number): number {
-  return Math.random() * (max - min) + min;
-}
-
-/**
- * Constrains a value between a minimum and maximum.
- */
-export function clamp(value: number, min: number, max: number): number {
-  return Math.min(Math.max(value, min), max);
-}
-
-/**
- * Calculates the distance (hypotenuse) between two points (or magnitude of a vector).
- * If x2/y2 are omitted, calculates magnitude of vector x1/y1.
- */
-export function dist(x1: number, y1: number, x2: number = 0, y2: number = 0): number {
-  const dx = x1 - x2;
-  const dy = y1 - y2;
-  return Math.sqrt(dx * dx + dy * dy);
-}
-
-/**
- * Calculates the angle in degrees between two points (or vector direction).
- */
-export function angle(x: number, y: number): number {
-  return Math.atan2(y, x) * (180 / Math.PI);
-}
+/**
+ * Linear Interpolation between two values.
+ */
+export function lerp(start: number, end: number, factor: number): number {
+  return start + (end - start) * factor;
+}
+
+/**
+ * Frame-rate independent damping (Time-based Lerp).
+ * Ensures smooth animation consistent across 60hz, 120hz, etc.
+ *
+ * @param a Current value
+ * @param b Target value
+ * @param lambda Smoothing factor (approx 1-20). Higher is faster.
+ * @param dt Delta time in seconds (not milliseconds)
+ */
+export function damp(a: number, b: number, lambda: number, dt: number): number {
+  return lerp(a, b, 1 - Math.exp(-lambda * dt));
+}
+
+/**
+ * Linear Interpolation between two angles in degrees, taking the shortest path.
+ * Handles wrap-around at 360 degrees.
+ */
+export function lerpAngle(start: number, end: number, factor: number): number {
+  const diff = ((((end - start) % 360) + 540) % 360) - 180;
+  return start + diff * factor;
+}
+
+/**
+ * Returns a random number between min and max.
+ * Usage: math.random(10, 20) -> 14.5
+ */
+export function random(min: number, max: number): number {
+  return Math.random() * (max - min) + min;
+}
+
+/**
+ * Constrains a value between a minimum and maximum.
+ */
+export function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+/**
+ * Calculates the distance (hypotenuse) between two points (or magnitude of a vector).
+ * If x2/y2 are omitted, calculates magnitude of vector x1/y1.
+ */
+export function dist(x1: number, y1: number, x2: number = 0, y2: number = 0): number {
+  const dx = x1 - x2;
+  const dy = y1 - y2;
+  return Math.sqrt(dx * dx + dy * dy);
+}
+
+/**
+ * Calculates the angle in degrees between two points (or vector direction).
+ */
+export function angle(x: number, y: number): number {
+  return Math.atan2(y, x) * (180 / Math.PI);
+}

package/src/options.ts

@@ -1,22 +1,22 @@
-import type { MouseState, ValueOrGetter } from '@supermousejs/core';
-
-/**
- * Returns a function that always resolves the option value.
- * Eliminates 'typeof' checks inside the render loop by normalizing
- * static values into getter functions during initialization.
- * 
- * @param option The option passed by the user
- * @param defaultValue Fallback value
- */
-export function normalize<T>(
-  option: ValueOrGetter<T> | undefined, 
-  defaultValue: T
-): (state: MouseState) => T {
-  if (option === undefined) {
-    return () => defaultValue;
-  }
-  if (typeof option === 'function') {
-    return option as (state: MouseState) => T;
-  }
-  return () => option;
-}
+import type { MouseState, ValueOrGetter } from "@supermousejs/core";
+
+/**
+ * Returns a function that always resolves the option value.
+ * Eliminates 'typeof' checks inside the render loop by normalizing
+ * static values into getter functions during initialization.
+ *
+ * @param option The option passed by the user
+ * @param defaultValue Fallback value
+ */
+export function normalize<T>(
+  option: ValueOrGetter<T> | undefined,
+  defaultValue: T
+): (state: MouseState) => T {
+  if (option === undefined) {
+    return () => defaultValue;
+  }
+  if (typeof option === "function") {
+    return option as (state: MouseState) => T;
+  }
+  return () => option;
+}