@supermousejs/core 2.0.5 → 2.2.0

package/src/systems/Input.ts

@@ -1,262 +0,0 @@
-
-import { MouseState, SupermouseOptions, InteractionState } from '../types';
-
-/**
- * The Sensor / State Writer.
- * 
- * This class listens to browser events (pointermove, pointerdown, hover) and mutates the shared `MouseState` object.
- * It acts as the "Producer" of data for the Supermouse system.
- * 
- * @internal This is an internal system class instantiated by `Supermouse`.
- */
-export class Input {
-  private mediaQueryList?: MediaQueryList;
-  private mediaQueryHandler?: (e: MediaQueryListEvent) => void;
-  private motionQuery?: MediaQueryList;
-  
-  /**
-   * Master switch for input processing. 
-   * Toggled by `Supermouse.enable()`/`disable()` or automatically by device capability checks.
-   */
-  public isEnabled: boolean = true;
-
-  /**
-   * Performance Optimization:
-   * We cache the resolved InteractionState for every element we encounter in a WeakMap.
-   */
-  private interactionCache = new WeakMap<HTMLElement, InteractionState>();
-
-  constructor(
-    private state: MouseState,
-    private options: SupermouseOptions,
-    private getHoverSelector: () => string, 
-    private onEnableChange: (enabled: boolean) => void
-  ) {
-    this.checkDeviceCapability();
-    this.checkMotionPreference();
-    this.bindEvents();
-  }
-
-  /**
-   * Automatically disables the custom cursor on devices without fine pointer control (e.g. phones/tablets).
-   * Relies on `matchMedia('(pointer: fine)')`.
-   */
-  private checkDeviceCapability() {
-    if (!this.options.autoDisableOnMobile) return;
-
-    this.mediaQueryList = window.matchMedia('(pointer: fine)');
-    this.updateEnabledState(this.mediaQueryList.matches);
-
-    this.mediaQueryHandler = (e: MediaQueryListEvent) => {
-      this.updateEnabledState(e.matches);
-    };
-    this.mediaQueryList.addEventListener('change', this.mediaQueryHandler);
-  }
-
-  /**
-   * Checks for `prefers-reduced-motion`.
-   * If true, the core physics engine will switch to instant snapping (high damping) to avoid motion sickness.
-   */
-  private checkMotionPreference() {
-   this.motionQuery = window.matchMedia('(prefer-reduced-motion: reduce)');
-   this.state.reducedMotion = this.motionQuery.matches;
-   
-   this.motionQuery.addEventListener('change',  e => {
-     this.state.reducedMotion = e.matches;
-   });
-  }
-  
-  private updateEnabledState(enabled: boolean) {
-    this.isEnabled = enabled;
-    this.onEnableChange(enabled);
-  }
-
-  // --- Interaction Parsing ---
-
-  /**
-   * Scrapes the DOM element for metadata to populate `state.interaction`.
-   * 
-   * **Strategy:**
-   * 1. Check WeakMap cache.
-   * 2. Apply config-based `rules`.
-   * 3. Scrape `dataset` (supermouse*).
-   * 4. Cache result.
-   */
-  private parseDOMInteraction(element: HTMLElement) {
-    // 0. Custom Strategy override
-    if (this.options.resolveInteraction) {
-      this.state.interaction = this.options.resolveInteraction(element);
-      return;
-    }
-
-    // 1. Check Cache
-    if (this.interactionCache.has(element)) {
-      this.state.interaction = this.interactionCache.get(element)!;
-      return;
-    }
-
-    const data: Record<string, any> = {};
-
-    // 2. Semantic Rules (Config-based)
-    if (this.options.rules) {
-      for (const [selector, rules] of Object.entries(this.options.rules)) {
-        if (element.matches(selector)) {
-          Object.assign(data, rules);
-        }
-      }
-    }
-
-    // 3. Dataset Scraping (Fast Native)
-    // Converts data-supermouse-my-val -> myVal
-    const dataset = element.dataset;
-    for (const key in dataset) {
-      if (key.startsWith('supermouse')) {
-        // 'supermouseColor' -> 'color'
-        // 'supermouseStick' -> 'stick'
-        const prop = key.slice(10);
-        if (prop) {
-          const cleanKey = prop.charAt(0).toLowerCase() + prop.slice(1);
-          const val = dataset[key];
-          // Treat empty string (bool attribute) as true
-          data[cleanKey] = val === '' ? true : val;
-        }
-      }
-    }
-
-    // 4. Cache and Set
-    this.interactionCache.set(element, data);
-    this.state.interaction = data;
-  }
-
-  // --- Handlers ---
-  
-  // Unified Pointer Event Handler
-  private handleMove = (e: PointerEvent) => {
-    if (!this.isEnabled) return;
-    
-    // Ignore non-mouse inputs if not on touch device (e.g. pen hovering but not touching)
-    // unless we strictly want to track everything. PointerType check is robust.
-    if (this.options.autoDisableOnMobile && e.pointerType === 'touch') return;
-
-    let x = e.clientX;
-    let y = e.clientY;
-
-    // Handle Custom Container Coordinates
-    if (this.options.container && this.options.container !== document.body) {
-      const rect = this.options.container.getBoundingClientRect();
-      x -= rect.left;
-      y -= rect.top;
-    }
-
-    this.state.pointer.x = x;
-    this.state.pointer.y = y;
-
-    if (!this.state.hasReceivedInput) {
-      this.state.hasReceivedInput = true;
-      this.state.target.x = this.state.smooth.x = x;
-      this.state.target.y = this.state.smooth.y = y;
-    }
-  };
-
-  private handleDown = () => { if (this.isEnabled) this.state.isDown = true; };
-  private handleUp = () => { if (this.isEnabled) this.state.isDown = false; };
-
-  private handleMouseOver = (e: MouseEvent) => {
-    if (!this.isEnabled) return;
-    const target = e.target as HTMLElement;
-
-    // 0. THE VETO: Explicit Ignore
-    if (target.closest('[data-supermouse-ignore]')) {
-      this.state.isNative = true;
-      return;
-    }
-
-    // 1. Dynamic Hover Check
-    const selector = this.getHoverSelector();
-    const hoverable = target.closest(selector);
-
-    if (hoverable) {
-      this.state.isHover = true;
-      this.state.hoverTarget = hoverable as HTMLElement;
-      this.parseDOMInteraction(this.state.hoverTarget);
-    }
-
-    // 2. Semantic Native Cursor Check (Configurable Strategy)
-    const strategy = this.options.ignoreOnNative;
-    
-    if (strategy) {
-      const checkTags = strategy === true || strategy === 'auto' || strategy === 'tag';
-      const checkCSS = strategy === true || strategy === 'auto' || strategy === 'css';
-      let isNative = false;
-
-      // A. Tag Check (Fast, O(1))
-      if (checkTags) {
-        // Check localName for speed (always lowercase)
-        const tag = target.localName;
-        if (tag === 'input' || tag === 'textarea' || tag === 'select' || target.isContentEditable) {
-          isNative = true;
-        }
-      }
-
-      // B. CSS Check (Slow, causes Layout Reflow)
-      // Only run if not already detected and strategy allows it.
-      if (!isNative && checkCSS) {
-        const style = window.getComputedStyle(target).cursor;
-        const supermouseAllowed = ['default', 'auto', 'pointer', 'none', 'inherit'];
-        if (!supermouseAllowed.includes(style)) {
-          isNative = true;
-        }
-      }
-
-      if (isNative) {
-        this.state.isNative = true;
-      }
-    }
-  };
-
-  private handleMouseOut = (e: MouseEvent) => {
-    if (!this.isEnabled) return;
-    const target = e.target as HTMLElement;
-
-    if (target === this.state.hoverTarget || target.contains(this.state.hoverTarget)) {
-       if (!e.relatedTarget || !(this.state.hoverTarget?.contains(e.relatedTarget as Node))) {
-          this.state.isHover = false;
-          this.state.hoverTarget = null;
-          this.state.interaction = {}; 
-       }
-    }
-
-    if (this.state.isNative) {
-      this.state.isNative = false;
-    }
-  };
-
-  private handleWindowLeave = () => {
-    if (this.options.hideOnLeave) {
-      this.state.hasReceivedInput = false;
-    }
-  };
-
-  private bindEvents() {
-    window.addEventListener('pointermove', this.handleMove, { passive: true });
-    window.addEventListener('pointerdown', this.handleDown, { passive: true });
-    window.addEventListener('pointerup', this.handleUp);
-    
-    document.addEventListener('mouseover', this.handleMouseOver);
-    document.addEventListener('mouseout', this.handleMouseOut);
-    document.addEventListener('mouseleave', this.handleWindowLeave);
-  }
-
-  public destroy() {
-    if (this.mediaQueryList && this.mediaQueryHandler) {
-      this.mediaQueryList.removeEventListener('change', this.mediaQueryHandler);
-    }
-    window.removeEventListener('pointermove', this.handleMove);
-    window.removeEventListener('pointerdown', this.handleDown);
-    window.removeEventListener('pointerup', this.handleUp);
-    
-    document.removeEventListener('mouseover', this.handleMouseOver);
-    document.removeEventListener('mouseout', this.handleMouseOut);
-    document.removeEventListener('mouseleave', this.handleWindowLeave);
-  }
-}

package/src/systems/Stage.ts

@@ -1,155 +0,0 @@
-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);
-  }
-}

package/src/systems/index.ts

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

package/src/utils/math.ts

@@ -1,20 +0,0 @@
-/**
- * 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);
-}