@supermousejs/core 2.4.1 → 2.4.2

package/src/__tests__/stage.spec.ts

@@ -1,235 +0,0 @@
-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

@@ -1,50 +0,0 @@
-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/index.ts

@@ -1,2 +0,0 @@
-export * from "./Supermouse";
-export * from "./types";

package/src/types.ts

@@ -1,165 +0,0 @@
-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/tsconfig.json

@@ -1,9 +0,0 @@
-{
-  "extends": "../../tsconfig.composite-lib.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "dist"
-  },
-  "include": ["src"],
-  "references": []
-}

package/tsconfig.tsbuildinfo

@@ -1 +0,0 @@
-{"fileNames":[],"fileInfos":[],"root":[],"options":{"allowImportingTsExtensions":true,"composite":true,"declaration":true,"declarationMap":true,"esModuleInterop":true,"module":99,"noFallthroughCasesInSwitch":true,"noImplicitAny":true,"noImplicitReturns":true,"noUnusedLocals":true,"noUnusedParameters":true,"outDir":"../../dist","rootDir":"../../src","skipLibCheck":true,"strict":true,"target":7,"useDefineForClassFields":true},"version":"5.8.3"}

package/vite.config.ts

@@ -1,32 +0,0 @@
-import { defineConfig } from "vite";
-import dts from "vite-plugin-dts";
-import path from "path";
-import { fileURLToPath } from "url";
-import { readFileSync } from "fs";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-const pkg = JSON.parse(readFileSync(path.resolve(__dirname, "package.json"), "utf-8"));
-
-export default defineConfig({
-  define: {
-    __VERSION__: JSON.stringify(pkg.version)
-  },
-  build: {
-    lib: {
-      entry: path.resolve(__dirname, "src/index.ts"),
-      name: "SupermouseCore",
-      fileName: (format) => (format === "es" ? "index.mjs" : "index.umd.js")
-    },
-    rollupOptions: {
-      external: [],
-      output: {
-        globals: {
-          "@supermousejs/core": "SupermouseCore"
-        }
-      }
-    }
-  },
-  plugins: [dts({ rollupTypes: true })]
-});

package/vitest.config.ts

@@ -1,10 +0,0 @@
-import { defineConfig } from "vitest/config";
-
-export default defineConfig({
-  test: {
-    environment: "jsdom",
-    globals: true,
-    setupFiles: ["src/__tests__/setup.ts"],
-    include: ["src/**/*.test.ts", "src/**/*.spec.ts"]
-  }
-});