@supermousejs/core 2.1.0 → 2.3.0

package/CHANGELOG.md

@@ -1,51 +1,68 @@
-# @supermousejs/core
-
-## 2.1.0
-
-### Minor Changes
-
-- 2590af3: - Refactored engine by removing 200 lines of redundant comments and typedocs, with appropriate re-reference to canon web docs
-  - Fixed a framework reactivity cache trap by moving away from WeakMap (computations are light and relatively inexpensive)
-  - Fixed double crashing by implementing a `try {} catch {}` safety net for plugin installation
-  - Fixed the Input layer not refreshing plugin states (particularly on hover) when DOM content is detached in reactive frameworks with `Node.isConnected`
-
-### 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
-
-## 2.0.5
-
-### Patch Changes
-
-- 67f771b: Add relevant npm metadata to package.json file
-
-## 2.0.4
-
-### Patch Changes
-
-- 993dc67: Updated supemousejs packages with proper author, license and url descriptors to repo
-
-## 2.0.3
-
-### Patch Changes
-
-- Add keywords to core package
-
-## 2.0.2
-
-### Patch Changes
-
-- ae219a0: Update READMEs with correct link to documentation
-
-## 2.0.1
-
-### Patch Changes
-
-- Add minimal README.md files to packages
-
-## 2.0.0
-
-### Major Changes
-
-- Initial v2.0.0 release
+# @supermousejs/core
+
+## 2.3.0
+
+### Minor Changes
+
+- 8dc8e06: cleanup and robustness pass: better case-insensitive data-\* handling, safer plugin lifecycle behavior, more reliable cursor restoration, and a more consistent reset/update flow
+- 600de13: added `dataPrefix` option for customizable data attribute handling, added a `start()` public method to manually start the raf loop and enhanced supermouse's resistance to bugs
+
+### Patch Changes
+
+- b72e264: Renamed `setCursor` to `setNativeCursor` for simplicity and removed redundant checks on `ignoreOnNative`
+
+## 2.2.0
+
+### Minor Changes
+
+- f6f44b2: Improved tree-shaking by consolidating subordinate files and helpers into the main module file
+
+## 2.1.0
+
+### Minor Changes
+
+- 2590af3: - Refactored engine by removing 200 lines of redundant comments and typedocs, with appropriate re-reference to canon web docs
+  - Fixed a framework reactivity cache trap by moving away from WeakMap (computations are light and relatively inexpensive)
+  - Fixed double crashing by implementing a `try {} catch {}` safety net for plugin installation
+  - Fixed the Input layer not refreshing plugin states (particularly on hover) when DOM content is detached in reactive frameworks with `Node.isConnected`
+
+### 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
+
+## 2.0.5
+
+### Patch Changes
+
+- 67f771b: Add relevant npm metadata to package.json file
+
+## 2.0.4
+
+### Patch Changes
+
+- 993dc67: Updated supemousejs packages with proper author, license and url descriptors to repo
+
+## 2.0.3
+
+### Patch Changes
+
+- Add keywords to core package
+
+## 2.0.2
+
+### Patch Changes
+
+- ae219a0: Update READMEs with correct link to documentation
+
+## 2.0.1
+
+### Patch Changes
+
+- Add minimal README.md files to packages
+
+## 2.0.0
+
+### Major Changes
+
+- Initial v2.0.0 release

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export declare const DEFAULT_HOVER_SELECTORS: string[];
 
+/* Excluded from this release type: Input */
+
 /**
  * The Interface for interaction state.
  * Plugins should use Module Augmentation to add their specific properties to this interface.
@@ -26,21 +28,21 @@ export declare interface MousePosition {
 }
 
 export declare interface MouseState {
-    /** The raw position of the input pointer (mouse/touch). */
+    /** The raw position from the latest pointer event, before smoothing is applied. */
     pointer: MousePosition;
-    /** The target position the cursor logic wants to reach. */
+    /** The current goal position that the core loop is driving toward. */
     target: MousePosition;
     /** The smoothed/interpolated position used for rendering. */
     smooth: MousePosition;
-    /** The current velocity vector of the smooth position. */
+    /** The current movement vector derived from the smoothed state. */
     velocity: MousePosition;
-    /** The angle of movement in degrees. Calculated from velocity. */
+    /** The current movement angle in degrees, derived from velocity. */
     angle: number;
     /** Whether the pointer is currently pressed down. */
     isDown: boolean;
     /** Whether the pointer is currently hovering over a registered interactive element. */
     isHover: boolean;
-    /** Whether the native cursor is currently forced visible by internal logic (e.g. input elements). */
+    /** Whether the runtime has temporarily restored the native cursor due to native-input heuristics. */
     isNative: boolean;
     /**
      * If set, this overrides all auto-detection logic.
@@ -69,11 +71,15 @@ export declare interface ShapeState {
     borderRadius: number;
 }
 
+/* Excluded from this release type: Stage */
+
 /**
- * Runtime Loop of Supermouse.
+ * Supermouse Runtime Loop
  *
- * This class orchestrates the application state, manages the animation loop (`requestAnimationFrame`),
- * and coordinates data flow between the Input system, the Stage system, and the Plugins.
+ * This class orchestrates the application state, manages the animation loop,
+ * and coordinates data flow between the internal systems, and the plugins.
+ *
+ * @default
  */
 export declare class Supermouse {
     static readonly version: string;
@@ -125,11 +131,11 @@ export declare class Supermouse {
      */
     get container(): HTMLDivElement;
     /**
-     * Manually override the native cursor visibility.
+     * Sets the native cursor visibility.
      *
-     * @param type 'auto' (Show Native), 'none' (Hide Native), or null (Resume Auto-detection)
+     * @param mode
      */
-    setCursor(type: "auto" | "none" | null): void;
+    setNativeCursor(mode: "hide" | "show" | "auto"): void;
     private init;
     enable(): void;
     disable(): void;
@@ -139,8 +145,13 @@ export declare class Supermouse {
      * @param plugin - The plugin object to install.
      */
     use(plugin: SupermousePlugin): this;
-    private resetPosition;
+    private reset;
     private startLoop;
+    /**
+     * Starts the animation loop. This is automatically called if `autoStart` is true.
+     * Plugins can call this method to resume the loop if it has been stopped.
+     */
+    start(): void;
     /**
      * Manually steps the animation loop.
      *
@@ -184,20 +195,24 @@ export declare interface SupermouseOptions {
     autoDisableOnMobile?: boolean;
     /**
      * Strategy for detecting when to fallback to the native cursor.
-     * - `true` / `'auto'`: Checks both HTML tags and CSS cursor styles (Accurate but slower).
+     * - `'auto'`: Checks both HTML tags and CSS cursor styles (Accurate but slower).
      * - `'tag'`: Checks only semantic tags like <input>, <textarea> (Fastest, prevents layout thrashing).
      * - `'css'`: Checks only computed CSS cursor styles (Slow, triggers reflow).
-     * - `false`: Never fallback to native cursor.
+     * - `null`: Never fallback to native cursor.
+     *
      * @default 'auto'
      */
-    ignoreOnNative?: boolean | NativeIgnoreStrategy;
+    ignoreOnNative?: NativeIgnoreStrategy | null;
     /**
-     * Whether to hide the native cursor via global CSS injection.
+     * Whether to hide the native cursor via scoped CSS injection on the container.
+     * When enabled, the stage toggles `cursor: none` on the configured container and
+     * on registered hover targets.
      * @default true
      */
     hideCursor?: boolean;
     /**
-     * Whether to hide the custom cursor when the mouse leaves the browser window.
+     * Whether to hide the custom cursor when the pointer leaves the browser viewport.
+     * When enabled the runtime clears the cursor back to an off-screen position to avoid stale hover state.
      * @default true
      */
     hideOnLeave?: boolean;
@@ -217,14 +232,24 @@ export declare interface SupermouseOptions {
     autoStart?: boolean;
     /**
      * Semantic rules mapping CSS selectors to interaction state.
+     * Rules are evaluated against hovered elements and merged into `state.interaction`.
+     * Matching data attributes on the same element are also read and can override or enrich the final object.
      * @example { 'button': { icon: 'pointer' } }
      */
     rules?: Record<string, InteractionState>;
     /**
      * Custom strategy to resolve interaction state from a hovered element.
-     * Overrides the default data-attribute scraping.
+     * When provided, this callback bypasses the default `rules` + `data-[prefix]-*` scraping and
+     * returns the interaction payload directly for the current hover target.
      */
     resolveInteraction?: (target: HTMLElement) => InteractionState;
+    /**
+     * The prefix used for data attributes to store hover metadata.
+     * For example, if dataPrefix is "supermouse", then the attribute would be "data-supermouse-*".
+     * This allows for multiple instances of Supermouse to coexist without conflicting data attributes.
+     * @default "supermouse"
+     */
+    dataPrefix?: string;
 }
 
 /**
@@ -239,7 +264,7 @@ export declare interface SupermousePlugin {
     isEnabled?: boolean;
     /** Called when `app.use()` is executed. */
     install?: (instance: Supermouse) => void;
-    /** Called on every animation frame. */
+    /** Called on every animation frame with the frame delta time in milliseconds. */
     update?: (instance: Supermouse, deltaTime: number) => void;
     /** Called when the plugin is removed or the app is destroyed. */
     destroy?: (instance: Supermouse) => void;
@@ -251,6 +276,7 @@ export declare interface SupermousePlugin {
 
 /**
  * Allows a property to be a static value or a function that returns the value based on state.
+ * This is primarily useful for plugin option definitions that should react to the current runtime state.
  */
 export declare type ValueOrGetter<T> = T | ((state: MouseState) => T);