@supermousejs/core 2.0.5 → 2.1.0

package/src/systems/Stage.ts

@@ -1,155 +1,126 @@
-let stageCount = 0;
-
-/**
- * The Environment / DOM Manager.
- *
- * This class handles the DOM container where the cursor lives and manages the global CSS
- * required to hide the default OS cursor without flickering.
- *
- * ## Why CSS Injection?
- * Simply adding `cursor: none` to the body isn't enough. Interactive elements like `<input>`
- * or `<a>` often have their own user-agent styles that force `cursor: text` or `cursor: pointer`.
- * This results in the "double cursor" glitch.
- *
- * The Stage system generates a scoped stylesheet that aggressively targets registered selectors
- * with `cursor: none !important` to ensure a seamless experience.
- *
- * @internal This is an internal system class instantiated by `Supermouse`.
- */
-export class Stage {
-  /** The container element appended to the document. Plugins must append here. */
-  public readonly element: HTMLDivElement;
-
-  private styleTag: HTMLStyleElement;
-  private id: string;
-  private scopeClass: string;
-
-  // Cache to prevent redundant DOM updates
-  private currentCursorState: 'none' | 'auto' | '' | null = null;
-
-  // Defaults for CSS hiding. We must override user-agent styles on these elements
-  // to prevent the native cursor from popping through.
-  private selectors: Set<string> = new Set([
-    'a', 'button', 'input', 'textarea', 'select',
-    '[role="button"]', '[tabindex]'
-  ]);
-
-  constructor(private container: HTMLElement = document.body, private hideNativeCursor: boolean) {
-    if (!container || !(container instanceof HTMLElement)) {
-      throw new Error(`[Supermouse] Invalid container: ${container}. Must be an HTMLElement.`);
-    }
-
-    const instanceId = stageCount++;
-    this.id = `supermouse-style-${instanceId}`;
-    this.scopeClass = `supermouse-scope-${instanceId}`;
-
-    const isBody = container === document.body;
-
-    // 1. Create Container
-    // If attached to body, use fixed positioning to cover viewport.
-    // If attached to a specific div, use absolute positioning to cover that div.
-    this.element = document.createElement('div');
-    Object.assign(this.element.style, {
-      position: isBody ? 'fixed' : 'absolute',
-      top: '0', left: '0', width: '100%', height: '100%',
-      pointerEvents: 'none',
-      zIndex: '9999',
-      opacity: '1',
-      transition: 'opacity 0.15s ease'
-    });
-
-    // Ensure parent is relative if we are using absolute positioning
-    if (!isBody) {
-        const computed = window.getComputedStyle(container);
-        if (computed.position === 'static') {
-            container.style.position = 'relative';
-        }
-    }
-
-    container.appendChild(this.element);
-
-    // 2. Create Dynamic Style Tag
-    this.styleTag = document.createElement('style');
-    this.styleTag.id = this.id;
-    document.head.appendChild(this.styleTag);
-
-    // 3. Apply Scope Class to Container
-    // This allows us to target CSS purely within this container (or body)
-    // preventing styles from leaking if multiple Supermouse instances exist.
-    this.container.classList.add(this.scopeClass);
-
-    // 4. Apply Initial Cursor State
-    if (this.hideNativeCursor) {
-      this.setNativeCursor('none');
-    }
-  }
-
-  /**
-   * Adds a new CSS selector to the "Hide Native Cursor" list.
-   * Called by `Supermouse` (and subsequently plugins) during install to ensure
-   * the native cursor is hidden on their specific interactive targets.
-   */
-  public addSelector(selector: string) {
-    this.selectors.add(selector);
-    if (this.hideNativeCursor) {
-      this.updateCursorCSS();
-    }
-  }
-
-  /**
-   * Controls the opacity of the entire stage (all custom cursor elements).
-   */
-  public setVisibility(visible: boolean) {
-    this.element.style.opacity = visible ? '1' : '0';
-  }
-
-  /**
-   * Toggles the visibility of the native cursor via CSS injection.
-   * @param type 'none' to hide, 'auto' to show.
-   */
-  public setNativeCursor(type: 'none' | 'auto' | '') {
-    // If global hiding is disabled via options, do nothing (unless specifically forcing auto)
-    if (!this.hideNativeCursor && type === 'none') return;
-
-    // PERFORMANCE FIX: Don't touch DOM if state hasn't changed
-    if (type === this.currentCursorState) return;
-    this.currentCursorState = type;
-
-    if (type === 'none') {
-      // 1. Hide on container directly (covers background/empty space)
-      this.container.style.cursor = 'none';
-      // 2. Hide on interactive elements (overrides UA stylesheet)
-      this.updateCursorCSS();
-    } else {
-      this.container.style.cursor = '';
-      this.styleTag.innerText = '';
-    }
-  }
-
-  private updateCursorCSS() {
-    const rawSelectors = Array.from(this.selectors);
-    if (rawSelectors.length === 0) {
-      this.styleTag.innerText = '';
-      return;
-    }
-
-    // Scoped Selector Logic:
-    // We prepend the scope class to every selector to ensure we don't bleed into
-    // other parts of the page if the user is using a specific container.
-    // e.g. .supermouse-scope-0 a, .supermouse-scope-0 button { ... }
-    const scopedSelectors = rawSelectors.map(s => `.${this.scopeClass} ${s}`).join(', ');
-
-    this.styleTag.innerText = `
-      ${scopedSelectors} {
-        cursor: none !important;
-      }
-    `;
-  }
-
-  public destroy() {
-    this.element.remove();
-    this.styleTag.remove();
-    this.container.style.cursor = '';
-    this.container.classList.remove(this.scopeClass);
-  }
-}
+let stageCount = 0;
+
+export class Stage {
+  /** The container element appended to the document. */
+  public readonly element: HTMLDivElement;
+  private styleTag: HTMLStyleElement;
+  private id: string;
+  private scopeClass: string;
+
+  private currentCursorState: "none" | "auto" | "" | null = null;
+
+  private selectors: Set<string> = new Set([
+    "a",
+    "button",
+    "input",
+    "textarea",
+    "select",
+    '[role="button"]',
+    "[tabindex]"
+  ]);
+
+  constructor(
+    private container: HTMLElement = document.body,
+    private hideNativeCursor: boolean
+  ) {
+    if (!container || !(container instanceof HTMLElement)) {
+      throw new Error(`[Supermouse] Invalid container: ${container}. Must be an HTMLElement.`);
+    }
+
+    const instanceId = stageCount++;
+    this.id = `supermouse-style-${instanceId}`;
+    this.scopeClass = `supermouse-scope-${instanceId}`;
+
+    const isBody = container === document.body;
+
+    this.element = document.createElement("div");
+    Object.assign(this.element.style, {
+      position: isBody ? "fixed" : "absolute",
+      top: "0",
+      left: "0",
+      width: "100%",
+      height: "100%",
+      pointerEvents: "none",
+      zIndex: "9999",
+      opacity: "1",
+      transition: "opacity 0.15s ease"
+    });
+
+    if (!isBody) {
+      const computed = window.getComputedStyle(container);
+      if (computed.position === "static") {
+        container.style.position = "relative";
+      }
+    }
+
+    container.appendChild(this.element);
+
+    this.styleTag = document.createElement("style");
+    this.styleTag.id = this.id;
+    document.head.appendChild(this.styleTag);
+
+    this.container.classList.add(this.scopeClass);
+
+    if (this.hideNativeCursor) {
+      this.setNativeCursor("none");
+    }
+  }
+
+  /**
+   * Adds a new CSS selector to the Hide Native Cursor list.
+   * Called by `Supermouse` (and subsequently plugins) during install to ensure
+   * the native cursor is hidden on their specific interactive targets.
+   */
+  public addSelector(selector: string) {
+    this.selectors.add(selector);
+    if (this.hideNativeCursor) {
+      this.updateCursorCSS();
+    }
+  }
+
+  public setVisibility(visible: boolean) {
+    this.element.style.opacity = visible ? "1" : "0";
+  }
+
+  /**
+   * Toggles the visibility of the native cursor via CSS injection.
+   * @param type 'none' to hide, 'auto' to show.
+   */
+  public setNativeCursor(type: "none" | "auto" | "") {
+    if (!this.hideNativeCursor && type === "none") return;
+
+    if (type === this.currentCursorState) return;
+    this.currentCursorState = type;
+
+    if (type === "none") {
+      this.container.style.cursor = "none";
+      this.updateCursorCSS();
+    } else {
+      this.container.style.cursor = "";
+      this.styleTag.innerText = "";
+    }
+  }
+
+  private updateCursorCSS() {
+    const rawSelectors = Array.from(this.selectors);
+    if (rawSelectors.length === 0) {
+      this.styleTag.innerText = "";
+      return;
+    }
+
+    const scopedSelectors = rawSelectors.map((s) => `.${this.scopeClass} ${s}`).join(", ");
+
+    this.styleTag.innerText = `
+      ${scopedSelectors} {
+        cursor: none !important;
+      }
+    `;
+  }
+
+  public destroy() {
+    this.element.remove();
+    this.styleTag.remove();
+    this.container.style.cursor = "";
+    this.container.classList.remove(this.scopeClass);
+  }
+}

package/src/systems/index.ts

@@ -1,2 +1,2 @@
-export * from './Stage';
-export * from './Input';
+export * from "./Stage";
+export * from "./Input";

package/src/types.ts

@@ -1,168 +1,168 @@
-import { Supermouse } from './Supermouse';
-
-export interface MousePosition {
-  x: number;
-  y: number;
-}
-
-export interface ShapeState {
-  width: number;
-  height: number;
-  borderRadius: number;
-}
-
-/**
- * The Interface for interaction state.
- * Plugins should use Module Augmentation to add their specific properties to this interface.
- *
- * @example
- * declare module '@supermousejs/core' {
- *   interface InteractionState {
- *     magnetic: boolean | number;
- *     text: string;
- *   }
- * }
- */
-export interface InteractionState {
-  /**
-   * Allow arbitrary keys for rapid prototyping.
-   * For type safety, use module augmentation to define expected keys.
-   */
-  [key: string]: any;
-}
-
-export interface MouseState {
-  /** The raw position of the input pointer (mouse/touch). */
-  pointer: MousePosition;
-  /** The target position the cursor logic wants to reach. */
-  target: MousePosition;
-  /** The smoothed/interpolated position used for rendering. */
-  smooth: MousePosition;
-  /** The current velocity vector of the smooth position. */
-  velocity: MousePosition;
-  /** The angle of movement in degrees. Calculated 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). */
-  isNative: boolean;
-  /**
-   * If set, this overrides all auto-detection logic.
-   * 'auto' = Force Native Cursor (Show)
-   * 'none' = Force Custom Cursor (Hide Native)
-   * null = Let the Core decide based on isNative/isHover
-   */
-  forcedCursor: 'auto' | 'none' | null;
-  /** The DOM element currently being hovered, if any. */
-  hoverTarget: HTMLElement | null;
-  /** Whether the user has `prefers-reduced-motion` enabled. */
-  reducedMotion: boolean;
-  /** Whether the system has received valid input coordinates at least once. */
-  hasReceivedInput: boolean;
-  /** Defines a specific geometric shape the cursor should conform to. */
-  shape: ShapeState | null;
-  /** Centralized store for hover metadata from data attributes. */
-  interaction: InteractionState;
-}
-
-export type NativeIgnoreStrategy = 'auto' | 'tag' | 'css';
-
-/**
- * Configuration options passed to the Supermouse constructor.
- */
-export interface SupermouseOptions {
-  /**
-   * The interpolation factor (0 to 1). Lower is smoother/slower.
-   * @default 0.15
-   */
-  smoothness?: number;
-  /**
-   * List of CSS selectors that trigger the "Hover" state.
-   * Overrides the default set if provided.
-   */
-  hoverSelectors?: string[];
-  /**
-   * Whether to enable custom cursor effects on touch devices.
-   * @default false
-   */
-  enableTouch?: boolean;
-  /**
-   * Whether to automatically disable the custom cursor on devices with coarse pointers.
-   * @default true
-   */
-  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).
-   * - `'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.
-   * @default 'auto'
-   */
-  ignoreOnNative?: boolean | NativeIgnoreStrategy;
-  /**
-   * Whether to hide the native cursor via global CSS injection.
-   * @default true
-   */
-  hideCursor?: boolean;
-  /**
-   * Whether to hide the custom cursor when the mouse leaves the browser window.
-   * @default true
-   */
-  hideOnLeave?: boolean;
-  /**
-   * List of plugins to initialize with the instance.
-   */
-  plugins?: SupermousePlugin[];
-  /**
-   * The DOM element to append the cursor stage to.
-   * @default document.body
-   */
-  container?: HTMLElement;
-  /**
-   * Whether to start the internal animation loop automatically.
-   * @default true
-   */
-  autoStart?: boolean;
-  /**
-   * Semantic rules mapping CSS selectors to interaction state.
-   * @example { 'button': { icon: 'pointer' } }
-   */
-  rules?: Record<string, InteractionState>;
-  /**
-   * Custom strategy to resolve interaction state from a hovered element.
-   * Overrides the default data-attribute scraping.
-   */
-  resolveInteraction?: (target: HTMLElement) => InteractionState;
-}
-
-/**
- * Helper type: Allows a property to be a static value OR a function that returns the value based on state.
- */
-export type ValueOrGetter<T> = T | ((state: MouseState) => T);
-
-/**
- * Interface for defining a Supermouse Plugin.
- */
-export interface SupermousePlugin {
-  /** Unique name for the plugin. Used for toggling/retrieval. */
-  name: string;
-  /** Execution priority. Lower numbers run first. */
-  priority?: number;
-  /** If false, update() will not be called. */
-  isEnabled?: boolean;
-
-  /** Called when `app.use()` is executed. */
-  install?: (instance: Supermouse) => void;
-  /** Called on every animation frame. */
-  update?: (instance: Supermouse, deltaTime: number) => void;
-  /** Called when the plugin is removed or the app is destroyed. */
-  destroy?: (instance: Supermouse) => void;
-
-  /** Called when the plugin is enabled via .enablePlugin() */
-  onEnable?: (instance: Supermouse) => void;
-  /** Called when the plugin is disabled via .disablePlugin() */
-  onDisable?: (instance: Supermouse) => void;
-}
+import type { Supermouse } from "./Supermouse";
+
+export interface MousePosition {
+  x: number;
+  y: number;
+}
+
+export interface ShapeState {
+  width: number;
+  height: number;
+  borderRadius: number;
+}
+
+/**
+ * The Interface for interaction state.
+ * Plugins should use Module Augmentation to add their specific properties to this interface.
+ *
+ * @example
+ * declare module '@supermousejs/core' {
+ *   interface InteractionState {
+ *     magnetic: boolean | number;
+ *     text: string;
+ *   }
+ * }
+ */
+export interface InteractionState {
+  /**
+   * Allow arbitrary keys for rapid prototyping.
+   * For type safety, use module augmentation to define expected keys.
+   */
+  [key: string]: any;
+}
+
+export interface MouseState {
+  /** The raw position of the input pointer (mouse/touch). */
+  pointer: MousePosition;
+  /** The target position the cursor logic wants to reach. */
+  target: MousePosition;
+  /** The smoothed/interpolated position used for rendering. */
+  smooth: MousePosition;
+  /** The current velocity vector of the smooth position. */
+  velocity: MousePosition;
+  /** The angle of movement in degrees. Calculated 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). */
+  isNative: boolean;
+  /**
+   * If set, this overrides all auto-detection logic.
+   * 'auto' = Force Native Cursor (Show)
+   * 'none' = Force Custom Cursor (Hide Native)
+   * null = Let the Core decide based on isNative/isHover
+   */
+  forcedCursor: "auto" | "none" | null;
+  /** The DOM element currently being hovered, if any. */
+  hoverTarget: HTMLElement | null;
+  /** Whether the user has `prefers-reduced-motion` enabled. */
+  reducedMotion: boolean;
+  /** Whether the system has received valid input coordinates at least once. */
+  hasReceivedInput: boolean;
+  /** Defines a specific geometric shape the cursor should conform to. */
+  shape: ShapeState | null;
+  /** Centralized store for hover metadata from data attributes. */
+  interaction: InteractionState;
+}
+
+export type NativeIgnoreStrategy = "auto" | "tag" | "css";
+
+/**
+ * Configuration options passed to the Supermouse constructor.
+ */
+export interface SupermouseOptions {
+  /**
+   * The interpolation factor (0 to 1). Lower is smoother/slower.
+   * @default 0.15
+   */
+  smoothness?: number;
+  /**
+   * List of CSS selectors that trigger the "Hover" state.
+   * Overrides the default set if provided.
+   */
+  hoverSelectors?: string[];
+  /**
+   * Whether to enable custom cursor effects on touch devices.
+   * @default false
+   */
+  enableTouch?: boolean;
+  /**
+   * Whether to automatically disable the custom cursor on devices with coarse pointers.
+   * @default true
+   */
+  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).
+   * - `'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.
+   * @default 'auto'
+   */
+  ignoreOnNative?: boolean | NativeIgnoreStrategy;
+  /**
+   * Whether to hide the native cursor via global CSS injection.
+   * @default true
+   */
+  hideCursor?: boolean;
+  /**
+   * Whether to hide the custom cursor when the mouse leaves the browser window.
+   * @default true
+   */
+  hideOnLeave?: boolean;
+  /**
+   * List of plugins to initialize with the instance.
+   */
+  plugins?: SupermousePlugin[];
+  /**
+   * The DOM element to append the cursor stage to.
+   * @default document.body
+   */
+  container?: HTMLElement;
+  /**
+   * Whether to start the internal animation loop automatically.
+   * @default true
+   */
+  autoStart?: boolean;
+  /**
+   * Semantic rules mapping CSS selectors to interaction state.
+   * @example { 'button': { icon: 'pointer' } }
+   */
+  rules?: Record<string, InteractionState>;
+  /**
+   * Custom strategy to resolve interaction state from a hovered element.
+   * Overrides the default data-attribute scraping.
+   */
+  resolveInteraction?: (target: HTMLElement) => InteractionState;
+}
+
+/**
+ * Allows a property to be a static value or a function that returns the value based on state.
+ */
+export type ValueOrGetter<T> = T | ((state: MouseState) => T);
+
+/**
+ * Interface for defining a Supermouse Plugin.
+ */
+export interface SupermousePlugin {
+  /** Unique name for the plugin. Used for toggling/retrieval. */
+  name: string;
+  /** Execution priority. Lower numbers run first. */
+  priority?: number;
+  /** If false, update() will not be called. */
+  isEnabled?: boolean;
+
+  /** Called when `app.use()` is executed. */
+  install?: (instance: Supermouse) => void;
+  /** Called on every animation frame. */
+  update?: (instance: Supermouse, deltaTime: number) => void;
+  /** Called when the plugin is removed or the app is destroyed. */
+  destroy?: (instance: Supermouse) => void;
+
+  /** Called when the plugin is enabled via .enablePlugin() */
+  onEnable?: (instance: Supermouse) => void;
+  /** Called when the plugin is disabled via .disablePlugin() */
+  onDisable?: (instance: Supermouse) => void;
+}

package/src/utils/math.ts

@@ -1,20 +1,11 @@
-/**
- * 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).
- */
-export function damp(a: number, b: number, lambda: number, dt: number): number {
-  return lerp(a, b, 1 - Math.exp(-lambda * dt));
-}
-
-/**
- * Calculates the angle in degrees between two points.
- */
-export function angle(x: number, y: number): number {
-  return Math.atan2(y, x) * (180 / Math.PI);
-}
+export function lerp(start: number, end: number, factor: number): number {
+  return start + (end - start) * factor;
+}
+
+export function damp(a: number, b: number, lambda: number, dt: number): number {
+  return lerp(a, b, 1 - Math.exp(-lambda * dt));
+}
+
+export function angle(x: number, y: number): number {
+  return Math.atan2(y, x) * (180 / Math.PI);
+}