@supermousejs/utils 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -1,49 +1,74 @@
-# @supermousejs/utils
-
-## 2.1.0
-
-### Minor Changes
-
-- 0a1652d: fixed build architecture and updated plugin metadata
-
-## 2.0.4
-
-### Patch Changes
-
-- 993dc67: Updated supemousejs packages with proper author, license and url descriptors to repo
-- Updated dependencies [993dc67]
-  - @supermousejs/core@2.0.4
-
-## 2.0.3
-
-### Patch Changes
-
-- Updated dependencies
-  - @supermousejs/core@2.0.3
-
-## 2.0.2
-
-### Patch Changes
-
-- ae219a0: Update READMEs with correct link to documentation
-- Updated dependencies [ae219a0]
-  - @supermousejs/core@2.0.2
-
-## 2.0.1
-
-### Patch Changes
-
-- Add minimal README.md files to packages
-- Updated dependencies
-  - @supermousejs/core@2.0.1
-
-## 2.0.0
-
-### Major Changes
-
-- Initial v2.0.0 release
-
-### Patch Changes
-
-- Updated dependencies
-  - @supermousejs/core@2.0.0
+# @supermousejs/utils
+
+## 2.2.0
+
+### Minor Changes
+
+- 9fe1a7b: - Implemented idiomatic approach to using supermouse/utils
+  - Rewrote `applyStyles`, `setTransform` and `setStyles` to share a global cache registry
+- 9fa6ece: Add `injectStyles` to safely handle injecting global CSS styles into the document head
+
+### Patch Changes
+
+- 6d70c18: remove legacy package and update supermouse domain in readme
+- 14fb5b6: Updated tsconfig to be reference-compliant with core, utils and zoetrope when required
+- Updated dependencies [6d70c18]
+- Updated dependencies [2590af3]
+- Updated dependencies [14fb5b6]
+  - @supermousejs/core@2.1.0
+
+## 2.1.1
+
+### Patch Changes
+
+- 67f771b: Add relevant npm metadata to package.json file
+- Updated dependencies [67f771b]
+  - @supermousejs/core@2.0.5
+
+## 2.1.0
+
+### Minor Changes
+
+- 0a1652d: fixed build architecture and updated plugin metadata
+
+## 2.0.4
+
+### Patch Changes
+
+- 993dc67: Updated supemousejs packages with proper author, license and url descriptors to repo
+- Updated dependencies [993dc67]
+  - @supermousejs/core@2.0.4
+
+## 2.0.3
+
+### Patch Changes
+
+- Updated dependencies
+  - @supermousejs/core@2.0.3
+
+## 2.0.2
+
+### Patch Changes
+
+- ae219a0: Update READMEs with correct link to documentation
+- Updated dependencies [ae219a0]
+  - @supermousejs/core@2.0.2
+
+## 2.0.1
+
+### Patch Changes
+
+- Add minimal README.md files to packages
+- Updated dependencies
+  - @supermousejs/core@2.0.1
+
+## 2.0.0
+
+### Major Changes
+
+- Initial v2.0.0 release
+
+### Patch Changes
+
+- Updated dependencies
+  - @supermousejs/core@2.0.0

package/LICENSE.md

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Sijibomi Olusunmbola
-
-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.
+MIT License
+
+Copyright (c) 2025 Sijibomi Olusunmbola
+
+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

@@ -1,15 +1,14 @@
-
-# @supermousejs/utils
-
-Shared utilities and helpers for the Supermouse ecosystem.
-Used primarily by plugin authors.
-
-## Features
-
-- **Math:** `lerp`, `damp` (frame-independent), `angle`, `dist`.
-- **DOM:** `createActor`, `setStyle` (cached), `setTransform`.
-- **Plugin:** `definePlugin` helper for type-safe plugin creation.
-
-## Documentation
-
-Full documentation and interactive playground available at [supermouse](https://supermouse.vercel.app) or [check out the repo](https://github.com/Whitestar14/supermouse-js).
+# @supermousejs/utils
+
+Shared utilities and helpers for the Supermouse ecosystem.
+Used primarily by plugin authors.
+
+## Features
+
+- **Math:** `lerp`, `damp` (frame-independent), `angle`, `dist`.
+- **DOM:** `createActor`, `setStyle` (cached), `setTransform`.
+- **Plugin:** `definePlugin` helper for type-safe plugin creation.
+
+## Documentation
+
+Full documentation and interactive playground available at [supermouse](https://supermouse.js.org) or [check out the repo](https://github.com/Whitestar14/supermouse-js).

package/dist/css.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Common cubic-bezier easing strings for CSS transitions.
+ */
+export declare const Easings: {
+    /** Good for entrance animations (starts fast, slows down) */
+    readonly EASE_OUT_EXPO: "cubic-bezier(0.16, 1, 0.3, 1)";
+    /** Good for elastic/bouncy UI elements */
+    readonly ELASTIC_OUT: "cubic-bezier(0.34, 1.56, 0.64, 1)";
+    /** Standard smooth movement */
+    readonly SMOOTH: "ease-out";
+};
+//# sourceMappingURL=css.d.ts.map

package/dist/css.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"css.d.ts","sourceRoot":"","sources":["../src/css.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,OAAO;IAClB,6DAA6D;;IAE7D,0CAA0C;;IAE1C,+BAA+B;;CAEvB,CAAC"}

package/dist/doctor.d.ts

@@ -0,0 +1,5 @@
+/**
+ * A diagnostic utility to find common CSS conflicts that cause cursor glitches.
+ */
+export declare function doctor(): void;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,MAAM,SA2CrB"}

package/dist/dom.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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 declare const injectStyles: (id: string, css: string) => void;
+/**
+ * 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 declare function applyStyles(el: HTMLElement, styles: Partial<CSSStyleDeclaration>): void;
+/**
+ * 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 declare function setStyle(el: HTMLElement, property: keyof CSSStyleDeclaration, value: string | number): void;
+/**
+ * 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 declare function setTransform(el: HTMLElement, x: number, y: number, rotation?: number, scaleX?: number, scaleY?: number, skewX?: number, skewY?: number): void;
+/**
+ * Calculates the bounding rectangle of an element relative to a container.
+ */
+export declare function projectRect(element: HTMLElement, container?: HTMLElement): DOMRect;
+/**
+ * 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 declare function createActor(tagName?: string): HTMLElement;
+/**
+ * Creates a circular HTML div using the standard actor base.
+ */
+export declare function createCircle(size: number, color: string): HTMLDivElement;
+/**
+ * Legacy alias for createActor.
+ * @deprecated Use createActor() instead.
+ */
+export declare function createDiv(): HTMLDivElement;
+//# sourceMappingURL=dom.d.ts.map

package/dist/dom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../src/dom.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GAAI,IAAI,MAAM,EAAE,KAAK,MAAM,SAQnD,CAAC;AAKF;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,mBAAmB,CAAC,QAgBhF;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CACtB,EAAE,EAAE,WAAW,EACf,QAAQ,EAAE,MAAM,mBAAmB,EACnC,KAAK,EAAE,MAAM,GAAG,MAAM,QAGvB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAC1B,EAAE,EAAE,WAAW,EACf,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,QAAQ,GAAE,MAAU,EACpB,MAAM,GAAE,MAAU,EAClB,MAAM,GAAE,MAAU,EAClB,KAAK,GAAE,MAAU,EACjB,KAAK,GAAE,MAAU,QAKlB;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,WAAW,EAAE,SAAS,GAAE,WAA2B,GAAG,OAAO,CAYjG;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,MAAc,GAAG,WAAW,CAYhE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,cAAc,CASxE;AAED;;;GAGG;AACH,wBAAgB,SAAS,IAAI,cAAc,CAE1C"}

package/dist/effects.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 declare function getVelocityDistortion(vx: number, vy: number, intensity?: number, maxStretch?: number): {
+    rotation: number;
+    scaleX: number;
+    scaleY: number;
+};
+//# sourceMappingURL=effects.d.ts.map

package/dist/effects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effects.d.ts","sourceRoot":"","sources":["../src/effects.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,SAAS,SAAQ,EAAE,UAAU,SAAM;;;;EAuBhG"}

package/dist/index.d.ts

@@ -1,227 +1,10 @@
-import { MouseState } from '../../core/src/index.ts';
-import { Supermouse } from '../../core/src/index.ts';
-import { SupermousePlugin } from '../../core/src/index.ts';
-import { ValueOrGetter } from '../../core/src/index.ts';
-
-/**
- * Calculates the angle in degrees between two points (or vector direction).
- */
-declare function angle(x: number, y: number): number;
-
-/**
- * Applies a dictionary of styles to an HTMLElement.
- */
-declare function applyStyles(el: HTMLElement, styles: Partial<CSSStyleDeclaration>): void;
-
-export declare interface BasePluginOptions {
-    name?: string;
-    isEnabled?: boolean;
-}
-
-/**
- * Constrains a value between a minimum and maximum.
- */
-declare function clamp(value: number, min: number, max: number): number;
-
-/**
- * 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')
- */
-declare function createActor(tagName?: string): HTMLElement;
-
-/**
- * Creates a circular HTML div using the standard actor base.
- */
-declare function createCircle(size: number, color: string): HTMLDivElement;
-
-/**
- * Legacy alias for createActor.
- * @deprecated Use createActor() instead.
- */
-declare function createDiv(): HTMLDivElement;
-
-/**
- * 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)
- */
-declare function damp(a: number, b: number, lambda: number, dt: number): number;
-
-export declare function definePlugin<E extends HTMLElement, O extends BasePluginOptions>(config: VisualConfig<E, O>, userOptions?: O): SupermousePlugin;
-
-export declare function definePlugin(config: LogicConfig, userOptions?: BasePluginOptions): SupermousePlugin;
-
-/**
- * Calculates the distance (hypotenuse) between two points (or magnitude of a vector).
- * If x2/y2 are omitted, calculates magnitude of vector x1/y1.
- */
-declare function dist(x1: number, y1: number, x2?: number, y2?: number): number;
-
-/**
- * Supermouse Doctor
- * A diagnostic utility to find common CSS conflicts that cause "Double Cursor" glitches.
- */
-export declare function doctor(): void;
-
-declare namespace dom {
-    export {
-        applyStyles,
-        setStyle,
-        setTransform,
-        projectRect,
-        createActor,
-        createCircle,
-        createDiv
-    }
-}
-export { dom }
-
-/**
- * Common cubic-bezier easing strings for CSS transitions.
- */
-export declare const Easings: {
-    /** Good for entrance animations (starts fast, slows down) */
-    readonly EASE_OUT_EXPO: "cubic-bezier(0.16, 1, 0.3, 1)";
-    /** Good for elastic/bouncy UI elements */
-    readonly ELASTIC_OUT: "cubic-bezier(0.34, 1.56, 0.64, 1)";
-    /** Standard smooth movement */
-    readonly SMOOTH: "ease-out";
-};
-
-declare namespace effects {
-    export {
-        getVelocityDistortion
-    }
-}
-export { effects }
-
-/**
- * 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)
- */
-declare function getVelocityDistortion(vx: number, vy: number, intensity?: number, maxStretch?: number): {
-    rotation: number;
-    scaleX: number;
-    scaleY: number;
-};
-
-/**
- * Standard Z-Index layers for the Supermouse ecosystem.
- * Relative to the Supermouse Container.
- */
-export declare const Layers: {
-    /** The top-most layer. For text, tooltips, and crucial UI. */
-    readonly OVERLAY: "400";
-    /** The main cursor layer. For the primary Dot/Pointer. */
-    readonly CURSOR: "300";
-    /** The secondary layer. For Rings, brackets, or followers. */
-    readonly FOLLOWER: "200";
-    /** The background layer. For trails, sparkles, and particles. */
-    readonly TRACE: "100";
-};
-
-/**
- * Linear Interpolation between two values.
- */
-declare function lerp(start: number, end: number, factor: number): number;
-
-/**
- * Linear Interpolation between two angles in degrees, taking the shortest path.
- * Handles wrap-around at 360 degrees.
- */
-declare function lerpAngle(start: number, end: number, factor: number): number;
-
-declare interface LogicConfig {
-    name: string;
-    priority?: number;
-    install?: (app: Supermouse) => void;
-    update?: (app: Supermouse, deltaTime: number) => void;
-    destroy?: (app: Supermouse) => void;
-    onEnable?: (app: Supermouse) => void;
-    onDisable?: (app: Supermouse) => void;
-    create?: never;
-}
-
-declare namespace math {
-    export {
-        lerp,
-        damp,
-        lerpAngle,
-        random,
-        clamp,
-        dist,
-        angle
-    }
-}
-export { math }
-
-/**
- * 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 declare function normalize<T>(option: ValueOrGetter<T> | undefined, defaultValue: T): (state: MouseState) => T;
-
-/**
- * Calculates the bounding rectangle of an element relative to a container.
- * Useful for logic plugins when the cursor is confined to a specific div.
- */
-declare function projectRect(element: HTMLElement, container?: HTMLElement): DOMRect;
-
-/**
- * Returns a random number between min and max.
- * Usage: math.random(10, 20) -> 14.5
- */
-declare function random(min: number, max: number): number;
-
-/**
- * Smart Style Setter.
- * Only writes to the DOM if the value has actually changed.
- */
-declare function setStyle(el: HTMLElement, property: keyof CSSStyleDeclaration, value: string | number): void;
-
-/**
- * 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
- */
-declare function setTransform(el: HTMLElement, x: number, y: number, rotation?: number, scaleX?: number, scaleY?: number, skewX?: number, skewY?: number): void;
-
-declare interface VisualConfig<E extends HTMLElement, O extends object> {
-    name: string;
-    /** Automatically register this attribute selector */
-    selector?: string;
-    /** Create and return the DOM Element */
-    create: (app: Supermouse) => E;
-    /** Map option keys to CSS properties */
-    styles?: Partial<Record<keyof O, keyof CSSStyleDeclaration>>;
-    /** Update loop with access to the element */
-    update?: (app: Supermouse, element: E, deltaTime: number) => void;
-    onEnable?: (app: Supermouse, element: E) => void;
-    onDisable?: (app: Supermouse, element: E) => void;
-    cleanup?: (element: E) => void;
-    destroy?: never;
-}
-
-export { }
+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';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,QAAQ,CAAC;AAC/B,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAC7B,OAAO,KAAK,OAAO,MAAM,WAAW,CAAC;AAErC,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,OAAO,CAAC;AACtB,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC"}