@supermousejs/core 2.3.0 → 2.4.1

package/src/__tests__/stage.spec.ts

@@ -0,0 +1,235 @@
+import { describe, it, expect, afterEach, beforeEach, vi } from "vitest";
+import { Stage } from "../Supermouse";
+
+describe("Supermouse Stage", () => {
+  let container: HTMLElement;
+  let stage: Stage;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+    document.body.appendChild(container);
+  });
+
+  afterEach(() => {
+    stage?.destroy();
+    document.body.innerHTML = "";
+    document.head.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  const getStyleTag = () =>
+    document.querySelector('style[id^="supermouse-style-"]') as HTMLStyleElement | null;
+
+  const hasClassPrefix = (el: HTMLElement, prefix: string) =>
+    Array.from(el.classList).some((c) => c.startsWith(prefix));
+
+  describe("Element creation & positioning", () => {
+    it("creates stage element with default styles", () => {
+      stage = new Stage(container, 9999);
+      const el = stage.element;
+      expect(el).toBeInstanceOf(HTMLDivElement);
+      expect(el.style.position).toBe("absolute");
+      expect(el.style.inset).toBe("0px");
+      expect(el.style.pointerEvents).toBe("none");
+      expect(el.style.zIndex).toBe("9999");
+      expect(el.style.opacity).toBe("1");
+      expect(el.style.transition).toBe("opacity 0.15s ease");
+      expect(container.contains(el)).toBe(true);
+    });
+
+    it("uses fixed positioning when container is body", () => {
+      stage = new Stage(document.body, 9999);
+      expect(stage.element.style.position).toBe("fixed");
+    });
+
+    it("throws if container is not an HTMLElement", () => {
+      expect(() => new Stage(null as any, 9999)).toThrowError(
+        "[Supermouse] Invalid container: null. Must be an HTMLElement."
+      );
+    });
+
+    it("warns if container is not connected", () => {
+      const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+      const detached = document.createElement("div");
+      new Stage(detached, 9999).destroy();
+      expect(warn).toHaveBeenCalledWith(
+        expect.stringContaining("container is not attached to the document")
+      );
+    });
+  });
+
+  describe("Stylesheet & selectors", () => {
+    it("injects style tag with cursor suppression rules on creation", () => {
+      stage = new Stage(container, 9999);
+      const styleTag = getStyleTag();
+      expect(styleTag).toBeInstanceOf(HTMLStyleElement);
+      expect(styleTag!.parentNode).toBe(document.head);
+      expect(styleTag!.innerText).toContain("cursor: none !important");
+    });
+
+    it("adds supermouse scope classes to container", () => {
+      stage = new Stage(container, 9999);
+      expect(container.classList.contains("supermouse-scope")).toBe(true);
+      expect(hasClassPrefix(container, "supermouse-scope-")).toBe(true);
+    });
+
+    it("addSelector updates the stylesheet", () => {
+      stage = new Stage(container, 9999);
+      const styleTag = getStyleTag()!;
+      const before = styleTag.innerText;
+
+      stage.addSelector(".my-selector");
+      const after = styleTag.innerText;
+
+      expect(before).not.toBe(after);
+      expect(after).toContain(".my-selector");
+    });
+
+    it("addSelectors batch updates stylesheet only once", () => {
+      stage = new Stage(container, 9999);
+      const styleTag = getStyleTag()!;
+      const originalInnerText = styleTag.innerText;
+
+      stage.addSelectors([".a", ".b", ".c"]);
+      const finalInnerText = styleTag.innerText;
+
+      expect(originalInnerText).not.toBe(finalInnerText);
+      expect(finalInnerText).toContain(".a");
+      expect(finalInnerText).toContain(".b");
+      expect(finalInnerText).toContain(".c");
+    });
+
+    it("scopes all hover selectors correctly, splitting comma groups", () => {
+      const container = document.createElement("div");
+      document.body.appendChild(container);
+      const stage = new Stage(container, 9999);
+
+      stage.addSelector("p, span, h1, h2");
+
+      const styleTag = document.querySelector("style[id^='supermouse-style-']")!;
+      const styleText = styleTag.innerText;
+
+      const scopeClass = Array.from(container.classList).find((c) =>
+        c.startsWith("supermouse-scope-")
+      );
+      const hideClass = `supermouse-hide-${scopeClass!.split("-").pop()}`;
+
+      expect(styleText).toContain(`.${scopeClass}.${hideClass} p`);
+      expect(styleText).toContain(`.${scopeClass}.${hideClass} span`);
+      expect(styleText).toContain(`.${scopeClass}.${hideClass} h1`);
+      expect(styleText).toContain(`.${scopeClass}.${hideClass} h2`);
+
+      expect(styleText).not.toMatch(/(^|,)\s*span\s*{/);
+      expect(styleText).not.toMatch(/(^|,)\s*h1\s*{/);
+
+      stage.destroy();
+      container.remove();
+    });
+  });
+
+  describe("Native cursor suppression", () => {
+    it("setNativeCursor toggles hide class and inline cursor style", () => {
+      stage = new Stage(container, 9999);
+      stage.setNativeCursor("none");
+      expect(container.style.cursor).toBe("none");
+      expect(hasClassPrefix(container, "supermouse-hide-")).toBe(true);
+
+      stage.setNativeCursor("auto");
+      expect(container.style.cursor).toBe("");
+      expect(hasClassPrefix(container, "supermouse-hide-")).toBe(false);
+    });
+
+    it("restores original container cursor when showing native", () => {
+      container.style.cursor = "pointer";
+      stage = new Stage(container, 9999);
+      stage.setNativeCursor("none");
+      expect(container.style.cursor).toBe("none"); // suppressed
+      expect(hasClassPrefix(container, "supermouse-hide-")).toBe(true);
+
+      stage.setNativeCursor("auto");
+      expect(container.style.cursor).toBe("pointer"); // restored
+      expect(hasClassPrefix(container, "supermouse-hide-")).toBe(false);
+    });
+
+    it("keeps original container cursor even if empty", () => {
+      container.style.cursor = "";
+      stage = new Stage(container, 9999);
+      stage.setNativeCursor("auto");
+      expect(container.style.cursor).toBe("");
+    });
+  });
+
+  describe("Visibility & layout", () => {
+    it("setVisibility toggles opacity", () => {
+      stage = new Stage(container, 9999);
+      stage.setVisibility(false);
+      expect(stage.element.style.opacity).toBe("0");
+      stage.setVisibility(true);
+      expect(stage.element.style.opacity).toBe("1");
+    });
+
+    it("sets container position to relative if static", () => {
+      container.style.position = "static";
+      stage = new Stage(container, 9999);
+      expect(container.style.position).toBe("relative");
+      stage.destroy();
+      expect(container.style.position).toBe("");
+    });
+
+    it("does not modify container position if already non-static", () => {
+      container.style.position = "absolute";
+      stage = new Stage(container, 9999);
+      expect(container.style.position).toBe("absolute");
+      stage.destroy();
+      expect(container.style.position).toBe("absolute");
+    });
+
+    it("does not modify position if container is body", () => {
+      stage = new Stage(document.body, 9999);
+      expect(document.body.style.position).toBe("");
+      stage.destroy();
+    });
+  });
+
+  describe("Cleanup", () => {
+    it("destroy removes stage element, style tag, and classes", () => {
+      stage = new Stage(container, 9999);
+      const el = stage.element;
+      const styleTag = getStyleTag()!;
+      expect(document.body.contains(el)).toBe(true);
+      expect(document.head.contains(styleTag)).toBe(true);
+
+      stage.destroy();
+
+      expect(document.body.contains(el)).toBe(false);
+      expect(document.head.contains(styleTag)).toBe(false);
+      expect(container.classList.contains("supermouse-scope")).toBe(false);
+      expect(hasClassPrefix(container, "supermouse-scope-")).toBe(false);
+      expect(hasClassPrefix(container, "supermouse-hide-")).toBe(false);
+      expect(container.style.cursor).toBe("");
+    });
+
+    it("destroy restores original container cursor", () => {
+      container.style.cursor = "crosshair";
+      stage = new Stage(container, 9999);
+      stage.destroy();
+      expect(container.style.cursor).toBe("crosshair");
+    });
+
+    it("creates unique style IDs for multiple instances", () => {
+      const stage1 = new Stage(container, 9999);
+      const stage2Container = document.createElement("div");
+      document.body.appendChild(stage2Container);
+      const stage2 = new Stage(stage2Container, 9999);
+
+      const styleTags = document.querySelectorAll('style[id^="supermouse-style-"]');
+      expect(styleTags.length).toBe(2);
+      const ids = Array.from(styleTags).map((tag) => tag.id);
+      expect(ids[0]).not.toBe(ids[1]);
+
+      stage1.destroy();
+      stage2.destroy();
+      stage2Container.remove();
+    });
+  });
+});

package/src/__tests__/suspend-resume.spec.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect, afterEach, vi } from "vitest";
+import { Supermouse } from "../Supermouse";
+
+describe("Suspend/Resume cursor state", () => {
+  let app: Supermouse;
+  let container: HTMLElement;
+
+  const hasClassPrefix = (el: HTMLElement, prefix: string) =>
+    Array.from(el.classList).some((c) => c.startsWith(prefix));
+
+  afterEach(() => {
+    app?.destroy();
+    document.body.innerHTML = "";
+    document.head.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  function createApp(cursor: "auto" | "custom" | "native" | "both" = "auto") {
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    app = new Supermouse({ container, cursor, autoStart: false });
+    window.dispatchEvent(
+      new PointerEvent("pointermove", { clientX: 100, clientY: 100, pointerType: "mouse" })
+    );
+    app.start();
+    app.step(performance.now() + 16);
+  }
+
+  it("resume() restores native cursor suppression synchronously", () => {
+    createApp("auto");
+    expect(hasClassPrefix(container, "supermouse-hide-")).toBe(true);
+    app.suspend();
+    expect(app.stage.style.opacity).toBe("0");
+    expect(hasClassPrefix(container, "supermouse-hide-")).toBe(true);
+
+    app.resume();
+    // Immediately after resume, hide class should still be present (native cursor hidden)
+    expect(hasClassPrefix(container, "supermouse-hide-")).toBe(true);
+    expect(container.style.cursor).toBe("none");
+  });
+
+  it("suspend() hides stage but preserves native cursor suppression state", () => {
+    createApp("auto");
+    expect(hasClassPrefix(container, "supermouse-hide-")).toBe(true);
+
+    app.suspend();
+    expect(app.stage.style.opacity).toBe("0");
+    expect(hasClassPrefix(container, "supermouse-hide-")).toBe(true);
+  });
+});

package/src/types.ts

@@ -1,183 +1,165 @@
-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 from the latest pointer event, before smoothing is applied. */
-  pointer: MousePosition;
-  /** The current goal position that the core loop is driving toward. */
-  target: MousePosition;
-  /** The smoothed/interpolated position used for rendering. */
-  smooth: MousePosition;
-  /** The current movement vector derived from the smoothed state. */
-  velocity: MousePosition;
-  /** 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 runtime has temporarily restored the native cursor due to native-input heuristics. */
-  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.
-   * - `'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).
-   * - `null`: Never fallback to native cursor.
-   *
-   * @default 'auto'
-   */
-  ignoreOnNative?: NativeIgnoreStrategy | null;
-  /**
-   * 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 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;
-  /**
-   * 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.
-   * 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.
-   * 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;
-}
-
-/**
- * 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 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 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;
-
-  /** 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 { SupermouseInstance } from "./Supermouse";
+
+export interface MousePosition {
+  x: number;
+  y: number;
+}
+
+export interface ShapeState {
+  width: number;
+  height: number;
+  borderRadius: number;
+}
+
+export type RuleValue = string | boolean | number;
+export type RuleSet = Record<string, RuleValue | ((el: HTMLElement) => RuleValue)>;
+export type RuleDefinition = RuleSet | ((el: HTMLElement) => RuleSet);
+
+/**
+ * Interaction state consumed by plugins.
+ * Extend via module augmentation for type safety.
+ *
+ * @example
+ * declare module '@supermousejs/core' {
+ *   interface InteractionState {
+ *     magnetic: boolean | number;
+ *     text: string;
+ *   }
+ * }
+ */
+export interface InteractionState {
+  /** Arbitrary keys allowed for quick prototyping. */
+  [key: string]: any;
+}
+
+export interface MouseState {
+  /** Raw pointer position from the latest event (before smoothing). */
+  pointer: MousePosition;
+  /** Goal position the core loop drives toward. */
+  target: MousePosition;
+  /** Smoothed position used for rendering. */
+  smooth: MousePosition;
+  /** Movement vector derived from smoothed state. */
+  velocity: MousePosition;
+  /** Remaining distance to target. */
+  displacement: MousePosition;
+  /** Movement angle in degrees. */
+  angle: number;
+  /** Pointer is pressed down. */
+  isDown: boolean;
+  /** Hovering over a registered interactive element. */
+  isHover: boolean;
+  /** Native cursor temporarily restored due to native-input heuristics. */
+  isNative: boolean;
+  /** Current cursor mode: auto, custom, native, or both. */
+  cursorMode: "auto" | "custom" | "native" | "both";
+  /** Currently hovered DOM element, if any. */
+  hoverTarget: HTMLElement | null;
+  /** User has `prefers-reduced-motion` enabled. */
+  reducedMotion: boolean;
+  /** At least one valid input coordinate received. */
+  hasReceivedInput: boolean;
+  /** Geometric shape the cursor should conform to. */
+  shape: ShapeState | null;
+  /** Centralized store for hover metadata from data attributes and rules. */
+  interaction: InteractionState;
+}
+
+/** Configuration options for 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;
+  /**
+   * Overall cursor mode.
+   * - `"auto"`: use built-in heuristic to decide per element.
+   * - `"custom"`: always show custom cursor, hide native.
+   * - `"native"`: always show native cursor, hide custom.
+   * - `"both"`: always show custom cursor **and** native cursor together (no suppression).
+   * @default "auto"
+   */
+  cursor?: "auto" | "custom" | "native" | "both";
+  /**
+   * Whether to hide the custom cursor when the pointer leaves the browser viewport.
+   * @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.
+   * Rules are evaluated against hovered elements and merged into `state.interaction`.
+   * @example { 'button': { icon: 'pointer' } }
+   */
+  rules?: Record<string, RuleDefinition>;
+  /**
+   * The prefix used for data attributes to store hover metadata.
+   * @default "supermouse"
+   */
+  dataPrefix?: string;
+  /**
+   * The `z-index` applied to the cursor stage element.
+   * @default 9999
+   */
+  zIndex?: number;
+}
+
+/** Static value or function that returns a value based on state. */
+export type ValueOrGetter<T> = T | ((state: MouseState) => T);
+
+/** Interface for defining a Supermouse plugin. */
+export interface SupermousePlugin {
+  /** Unique plugin name. */
+  name: string;
+  /** Execution priority; lower runs first. */
+  priority?: number;
+  /** If false, `update()` will not be called. */
+  isEnabled?: boolean;
+  /** Root DOM element, if any. Hidden when plugin disabled. */
+  element?: HTMLElement | SVGElement;
+
+  /** Called when `app.use()` is executed. */
+  install?: (instance: SupermouseInstance) => void;
+  /** Called every animation frame with delta time in ms. */
+  update?: (instance: SupermouseInstance, deltaTime: number) => void;
+  /** Called when plugin removed or instance destroyed. */
+  destroy?: (instance: SupermouseInstance) => void;
+
+  /** Called when plugin enabled via `.enablePlugin()`. */
+  onEnable?: (instance: SupermouseInstance) => void;
+  /** Called when plugin disabled via `.disablePlugin()`. */
+  onDisable?: (instance: SupermouseInstance) => void;
+  /**
+   * Called before the plugin is disabled.
+   */
+  onBeforeDisable?(instance: SupermouseInstance): void | Promise<void>;
+}

package/vitest.config.ts

@@ -5,6 +5,6 @@ export default defineConfig({
     environment: "jsdom",
     globals: true,
     setupFiles: ["src/__tests__/setup.ts"],
-    include: ["src/**/*.test.ts"]
+    include: ["src/**/*.test.ts", "src/**/*.spec.ts"]
   }
 });